refactor(plugins): decouple plugin framework from gateway settings

.env.example

@@ -138,9 +138,6 @@ LOG_FOLDER=logs
 # Local OTEL collector endpoint
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
 
-# Rich CLI output for plugin tooling
-PLUGINS_CLI_MARKUP_MODE=rich
-
 # =============================================================================
 # Hot toggles (commented quick switches)
 # =============================================================================
@@ -2149,16 +2146,116 @@ PLUGINS_CLI_MARKUP_MODE=rich
 # Default: "" (no custom labels)
 # METRICS_CUSTOM_LABELS=
 
+# -----------------------------------------------------------------------------
+# Plugin Framework Settings
+# -----------------------------------------------------------------------------
+# The plugin framework has its own configuration via pydantic-settings with the
+# PLUGINS_ env var prefix. These settings allow the plugin framework to operate
+# independently of the gateway configuration (mcpgateway.config).
+#
+# When the plugin framework is used standalone (e.g., via the mcpplugins CLI or
+# as a library), only these PLUGINS_-prefixed variables are needed. When running
+# inside the gateway, both the gateway settings (above) AND these framework
+# settings are in effect.
+#
+# The plugin framework settings share some env var names with the gateway
+# (e.g. PLUGINS_ENABLED, PLUGINS_CLI_MARKUP_MODE). Other settings mirror
+# gateway-level HTTPX_*/SKIP_SSL_VERIFY but are scoped to plugin requests:
+#   HTTPX_CONNECT_TIMEOUT → PLUGINS_HTTPX_CONNECT_TIMEOUT
+#   HTTPX_READ_TIMEOUT    → PLUGINS_HTTPX_READ_TIMEOUT
+#   SKIP_SSL_VERIFY       → PLUGINS_SKIP_SSL_VERIFY
+
 # Plugin Framework Configuration
 # Enable the plugin system for extending gateway functionality
 # Options: true, false (default)
-# When true: Loads and executes plugins from PLUGIN_CONFIG_FILE
+# When true: Loads and executes plugins from PLUGINS_CONFIG_FILE
 # PLUGINS_ENABLED=false
 
 # Path to the plugin configuration file
 # Contains plugin definitions, hooks, and settings
 # Default: plugins/config.yaml
-# PLUGIN_CONFIG_FILE=plugins/config.yaml
+# PLUGINS_CONFIG_FILE=plugins/config.yaml
+
+# Plugin execution timeout in seconds
+# PLUGINS_PLUGIN_TIMEOUT=30
+
+# Plugin framework log level
+# PLUGINS_LOG_LEVEL=INFO
+
+# Skip SSL/TLS certificate verification for plugin HTTP requests
+# WARNING: Only use in development or with self-signed certificates
+# PLUGINS_SKIP_SSL_VERIFY=false
+
+# HTTP client pool settings for plugin framework
+# These mirror the gateway HTTPX_* settings but are scoped to plugin requests
+# PLUGINS_HTTPX_MAX_CONNECTIONS=200
+# PLUGINS_HTTPX_MAX_KEEPALIVE_CONNECTIONS=100
+# PLUGINS_HTTPX_KEEPALIVE_EXPIRY=30.0
+# PLUGINS_HTTPX_CONNECT_TIMEOUT=5.0
+# PLUGINS_HTTPX_READ_TIMEOUT=120.0
+# PLUGINS_HTTPX_WRITE_TIMEOUT=30.0
+# PLUGINS_HTTPX_POOL_TIMEOUT=10.0
+
+# Optional defaults for mTLS when connecting to external MCP plugins (STREAMABLEHTTP transport)
+# Provide file paths inside the container. Plugin-specific TLS blocks override these defaults.
+# PLUGINS_CLIENT_MTLS_CA_BUNDLE=/app/certs/plugins/ca.crt
+# PLUGINS_CLIENT_MTLS_CERTFILE=/app/certs/plugins/gateway-client.pem
+# PLUGINS_CLIENT_MTLS_KEYFILE=/app/certs/plugins/gateway-client.key
+# PLUGINS_CLIENT_MTLS_KEYFILE_PASSWORD=
+# PLUGINS_CLIENT_MTLS_VERIFY=true
+# PLUGINS_CLIENT_MTLS_CHECK_HOSTNAME=true
+
+# Optional defaults for plugin server TLS when exposing plugins over HTTP
+# PLUGINS_SERVER_SSL_ENABLED=false
+# PLUGINS_SERVER_SSL_KEYFILE=/app/certs/plugins/server.key
+# PLUGINS_SERVER_SSL_CERTFILE=/app/certs/plugins/server.pem
+# PLUGINS_SERVER_SSL_CA_CERTS=/app/certs/plugins/ca.crt
+# PLUGINS_SERVER_SSL_CERT_REQS=2
+# PLUGINS_SERVER_SSL_KEYFILE_PASSWORD=
+
+# Plugin MCP server bind settings
+# PLUGINS_SERVER_HOST=0.0.0.0
+# PLUGINS_SERVER_PORT=9000
+# PLUGINS_SERVER_UDS=/tmp/mcpgateway-plugins.sock
+
+# Plugin server runtime (external MCP server)
+# PLUGINS_TRANSPORT=stdio
+# PLUGINS_CONFIG_PATH=./resources/plugins/config.yaml
+
+# Optional defaults for mTLS when connecting to external plugins over gRPC
+# PLUGINS_GRPC_CLIENT_MTLS_CA_BUNDLE=/app/certs/plugins/grpc-ca.crt
+# PLUGINS_GRPC_CLIENT_MTLS_CERTFILE=/app/certs/plugins/grpc-client.pem
+# PLUGINS_GRPC_CLIENT_MTLS_KEYFILE=/app/certs/plugins/grpc-client.key
+# PLUGINS_GRPC_CLIENT_MTLS_KEYFILE_PASSWORD=
+# PLUGINS_GRPC_CLIENT_MTLS_VERIFY=true
+
+# Optional defaults for plugin gRPC server TLS
+# PLUGINS_GRPC_SERVER_SSL_ENABLED=false
+# PLUGINS_GRPC_SERVER_SSL_KEYFILE=/app/certs/plugins/grpc-server.key
+# PLUGINS_GRPC_SERVER_SSL_CERTFILE=/app/certs/plugins/grpc-server.pem
+# PLUGINS_GRPC_SERVER_SSL_CA_CERTS=/app/certs/plugins/grpc-ca.crt
+# PLUGINS_GRPC_SERVER_SSL_CLIENT_AUTH=none
+# PLUGINS_GRPC_SERVER_SSL_KEYFILE_PASSWORD=
+
+# Plugin gRPC server bind settings
+# PLUGINS_GRPC_SERVER_HOST=0.0.0.0
+# PLUGINS_GRPC_SERVER_PORT=50051
+# PLUGINS_GRPC_SERVER_UDS=/tmp/mcpgateway-plugins-grpc.sock
+
+# Unix domain socket transport for plugin communication
+# PLUGINS_UNIX_SOCKET_PATH=/tmp/mcpgateway-plugins-unix.sock
+
+# Enable auto-completion for plugins CLI
+# PLUGINS_CLI_COMPLETION=false
+
+# Set markup mode for plugins CLI
+# Valid options:
+#  rich: use rich markup
+#  markdown: allow markdown in help strings
+#  disabled: disable markup
+# If unset (commented out), uses "rich" if rich is detected, otherwise disables it.
+# Project defaults block sets PLUGINS_CLI_MARKUP_MODE=rich
+PLUGINS_CLI_MARKUP_MODE=rich
 
 # =============================================================================
 # Well-Known URI Configuration
@@ -2411,25 +2508,6 @@ PLUGINS_CLI_MARKUP_MODE=rich
 # Direct env read (mcpgateway/observability.py)
 # MCP_TESTING=0
 
-# --- Plugin mTLS defaults (direct env reads) ---------------------------------
-
-# Optional defaults for mTLS when connecting to external MCP plugins (STREAMABLEHTTP transport)
-# Provide file paths inside the container. Plugin-specific TLS blocks override these defaults.
-# PLUGINS_CLIENT_MTLS_CA_BUNDLE=/app/certs/plugins/ca.crt
-# PLUGINS_CLIENT_MTLS_CERTFILE=/app/certs/plugins/gateway-client.pem
-# PLUGINS_CLIENT_MTLS_KEYFILE=/app/certs/plugins/gateway-client.key
-# PLUGINS_CLIENT_MTLS_KEYFILE_PASSWORD=
-# PLUGINS_CLIENT_MTLS_VERIFY=true
-# PLUGINS_CLIENT_MTLS_CHECK_HOSTNAME=true
-
-# Optional defaults for plugin server TLS when exposing plugins over HTTP
-# PLUGINS_SERVER_SSL_ENABLED=false
-# PLUGINS_SERVER_SSL_KEYFILE=/app/certs/plugins/server.key
-# PLUGINS_SERVER_SSL_CERTFILE=/app/certs/plugins/server.pem
-# PLUGINS_SERVER_SSL_CA_CERTS=/app/certs/plugins/ca.crt
-# PLUGINS_SERVER_SSL_CERT_REQS=2
-# PLUGINS_SERVER_SSL_KEYFILE_PASSWORD=
-
 # --- Auxiliary tools and CLIs (non-gateway runtime) --------------------------
 
 # These are used by helper tools, CLIs, and SDK wrappers (not the main gateway server).
@@ -2466,10 +2544,6 @@ PLUGINS_CLI_MARKUP_MODE=rich
 # MCP_DEBUG=
 # CONTAINER=false
 
-# Plugin server runtime (external MCP server)
-# PLUGINS_TRANSPORT=stdio
-# PLUGINS_CONFIG_PATH=./resources/plugins/config.yaml
-
 # ToolOps LLM provider envs (mcpgateway/toolops/utils/llm_util.py)
 # LLM_PROVIDER=openai
 # NOTE: MAX_TOEKNS is misspelled in code; use the exact env name shown below.
@@ -2571,22 +2645,9 @@ PLUGINS_CLI_MARKUP_MODE=rich
 # Default: 30 seconds. Range: 5-3600 seconds.
 # A2A_STATS_CACHE_TTL=30
 
-# Enable auto-completion for plugins CLI
-# PLUGINS_CLI_COMPLETION=false
-
 # Project defaults block sets MCPGATEWAY_UI_TOOL_TEST_TIMEOUT=120000 for local dev
 # MCPGATEWAY_UI_TOOL_TEST_TIMEOUT=60000
 
-
-# Set markup mode for plugins CLI
-# Valid options:
-#  rich: use rich markup
-#  markdown: allow markdown in help strings
-#  disabled: disable markup
-# If unset (commented out), uses "rich" if rich is detected, otherwise disables it.
-# Project defaults block sets PLUGINS_CLI_MARKUP_MODE=rich
-# PLUGINS_CLI_MARKUP_MODE=rich
-
 # =============================================================================
 # Security Validation Settings
 # =============================================================================

AGENTS.md

@@ -128,7 +128,7 @@ MCPGATEWAY_UI_ENABLED=true
 MCPGATEWAY_ADMIN_API_ENABLED=true
 MCPGATEWAY_A2A_ENABLED=true
 PLUGINS_ENABLED=true
-PLUGIN_CONFIG_FILE=plugins/config.yaml
+PLUGINS_CONFIG_FILE=plugins/config.yaml
 
 # Logging
 LOG_LEVEL=INFO

DEVELOPING.md

@@ -421,7 +421,7 @@ plugins:
 ```bash
 # Enable plugin system
 export PLUGINS_ENABLED=true
-export PLUGIN_CONFIG_FILE=plugins/config.yaml
+export PLUGINS_CONFIG_FILE=plugins/config.yaml
 
 # Test plugin
 make dev

Makefile

@@ -27,12 +27,20 @@ HANDSDOWN_PARAMS  = -o $(DOCS_DIR)/ -n $(PROJECT_NAME) --name "MCP Gateway" --cl
 
 TEST_DOCS_DIR ?= $(DOCS_DIR)/docs/test
 
+# Virtual-environment variables
+VENVS_DIR ?= $(HOME)/.venv
+VENV_DIR  ?= $(VENVS_DIR)/$(PROJECT_NAME)
+
 # -----------------------------------------------------------------------------
 # Project-wide clean-up targets
 # -----------------------------------------------------------------------------
+COVERAGE_DIR ?= $(DOCS_DIR)/docs/coverage
+LICENSES_MD  ?= $(DOCS_DIR)/docs/test/licenses.md
+METRICS_MD   ?= $(DOCS_DIR)/docs/metrics/loc.md
+
 DIRS_TO_CLEAN := __pycache__ .pytest_cache .tox .ruff_cache .pyre .mypy_cache .pytype \
 	dist build site .eggs *.egg-info .cache htmlcov certs \
-	$(VENV_DIR) $(VENV_DIR).sbom $(COVERAGE_DIR) \
+	$(VENV_DIR) $(VENV_DIR).sbom $(COVERAGE_DIR) htmlcov-doctest htmlcov_ai_normalizer \
 	node_modules .mutmut-cache html
 
 FILES_TO_CLEAN := .coverage .coverage.* coverage.xml mcp.prof mcp.pstats mcp.db-* \
@@ -71,10 +79,6 @@ METRICS_MD   ?= $(DOCS_DIR)/docs/metrics/loc.md
 CONTAINER_MEMORY = 2048m
 CONTAINER_CPUS   = 2
 
-# Virtual-environment variables
-VENVS_DIR ?= $(HOME)/.venv
-VENV_DIR  ?= $(VENVS_DIR)/$(PROJECT_NAME)
-
 # -----------------------------------------------------------------------------
 # OS Specific
 # -----------------------------------------------------------------------------

charts/mcp-stack/README.md

@@ -229,7 +229,7 @@ Kubernetes: `>=1.21.0-0`
 | mcpContextForge.config.PLUGINS_MTLS_CLIENT_KEY | string | `""` |  |
 | mcpContextForge.config.PLUGINS_MTLS_CLIENT_KEY_PASSWORD | string | `""` |  |
 | mcpContextForge.config.PLUGINS_MTLS_VERIFY | string | `"true"` |  |
-| mcpContextForge.config.PLUGIN_CONFIG_FILE | string | `"plugins/config.yaml"` |  |
+| mcpContextForge.config.PLUGINS_CONFIG_FILE | string | `"plugins/config.yaml"` | `PLUGIN_CONFIG_FILE` also accepted for backwards compatibility |
 | mcpContextForge.config.PORT | string | `"4444"` |  |
 | mcpContextForge.config.PROMPT_CACHE_SIZE | string | `"100"` |  |
 | mcpContextForge.config.PROMPT_RENDER_TIMEOUT | string | `"10"` |  |

charts/mcp-stack/templates/deployment-mcpgateway.yaml

@@ -235,7 +235,7 @@ spec:
           {{- if .Values.mcpContextForge.pluginConfig.enabled }}
           volumeMounts:
             - name: plugin-config-volume
-              mountPath: /app/{{ .Values.mcpContextForge.config.PLUGIN_CONFIG_FILE }}
+              mountPath: /app/{{ coalesce .Values.mcpContextForge.config.PLUGINS_CONFIG_FILE .Values.mcpContextForge.config.PLUGIN_CONFIG_FILE "plugins/config.yaml" }}
               subPath: config.yaml
           {{- end }}
 {{- if .Values.mcpContextForge.pluginConfig.enabled }}

charts/mcp-stack/values.yaml

@@ -566,7 +566,8 @@ mcpContextForge:
 
     # ─ Plugin Configuration ─
     PLUGINS_ENABLED: "false"         # enable the plugin framework
-    PLUGIN_CONFIG_FILE: "plugins/config.yaml" # path to main plugin configuration file
+    PLUGINS_CONFIG_FILE: "plugins/config.yaml" # path to main plugins configuration file (PLUGIN_CONFIG_FILE also accepted)
+    PLUGIN_CONFIG_FILE: "plugins/config.yaml" # path to main plugins configuration file (deprecated, use PLUGINS_CONFIG_FILE)
     PLUGINS_CLIENT_MTLS_CA_BUNDLE: ""        # default CA bundle for external plugins (optional)
     PLUGINS_CLIENT_MTLS_CERTFILE: ""         # gateway client certificate for plugin mTLS
     PLUGINS_CLIENT_MTLS_KEYFILE: ""          # gateway client key for plugin mTLS (optional)
@@ -581,6 +582,16 @@ mcpContextForge:
     PLUGINS_SERVER_SSL_KEYFILE_PASSWORD: ""  # password for plugin server key (optional)
     PLUGINS_CLI_COMPLETION: "false"  # enable auto-completion for plugins CLI
     PLUGINS_CLI_MARKUP_MODE: "rich"  # set markup mode for plugins CLI (rich, markdown, or disabled)
+    PLUGINS_PLUGIN_TIMEOUT: "30"               # plugin execution timeout (seconds)
+    PLUGINS_LOG_LEVEL: "INFO"                  # plugin framework log level
+    PLUGINS_SKIP_SSL_VERIFY: "false"           # skip TLS verification for plugin HTTP requests
+    PLUGINS_HTTPX_CONNECT_TIMEOUT: "5.0"       # plugin HTTP client TCP connect timeout (seconds)
+    PLUGINS_HTTPX_READ_TIMEOUT: "120.0"        # plugin HTTP client read timeout (seconds)
+    PLUGINS_HTTPX_WRITE_TIMEOUT: "30.0"        # plugin HTTP client write timeout (seconds)
+    PLUGINS_HTTPX_POOL_TIMEOUT: "10.0"         # plugin HTTP client pool timeout (seconds)
+    PLUGINS_HTTPX_MAX_CONNECTIONS: "200"        # plugin HTTP client max connections
+    PLUGINS_HTTPX_MAX_KEEPALIVE_CONNECTIONS: "100" # plugin HTTP client max keepalive connections
+    PLUGINS_HTTPX_KEEPALIVE_EXPIRY: "30.0"     # plugin HTTP client keepalive expiry (seconds)
 
     # ─ OpenTelemetry Observability ─
     OTEL_ENABLE_OBSERVABILITY: "false" # master switch for observability

docs/docs/architecture/adr/019-modular-architecture-split.md

@@ -158,7 +158,7 @@ CACHE_TYPE=redis|memory|database
 
 # Plugin system
 PLUGINS_ENABLED=true
-PLUGIN_CONFIG_FILE=plugins/config.yaml
+PLUGINS_CONFIG_FILE=plugins/config.yaml
 
 # Transport protocols
 MCPGATEWAY_SSE_ENABLED=true