feat: initial revision of adding plugin support.

[terylt]

✨ Feature / Enhancement PR

🔗 Epic / Issue

Closes #319

---

🚀 Summary (1-2 sentences)

This PR adds plugin capabilities at special hook points throughout the MCP Context Forge to be able to perform AI safety, security, and business processing. More details in the issue.

🧪 Checks

• make lint passes
• make test passes
• CHANGELOG updated (if user-facing)

---

[crivetimihai]

🔌 MCP Gateway Plugin Framework - PR Review & Testing Guide

📊 Overview

This PR implements an MVP plugin framework for MCP Gateway, enabling extensible pre/post processing hooks throughout the request lifecycle. The framework supports both native plugins (Python, run in-process) and external microservice plugins (LLMGuard, OPA, etc).

✅ What's Implemented

Core Framework

• Plugin Base Classes - Abstraction for plugin development (Plugin, PluginRef)
• Plugin Manager - Singleton managing plugin lifecycle, registration, and execution
• Configuration System - YAML-based configs with environment variable substitution
• Hook System - Currently implements prompt_pre_fetch and prompt_post_fetch hooks
• Execution Modes - enforce (blocks requests), permissive (logs only), disabled
• Priority Ordering - Plugins execute by priority (lower number = higher priority)
• Conditional Execution - Plugins can filter by prompts, servers, tenants, users
• Context Management - Request-scoped context with state persistence between hooks

Example Plugins

• SearchReplacePlugin - Native plugin demonstrating text transformation
• PIIFilterPlugin (stub) - Shows pattern for PII detection/masking
• LLMGuardPlugin (stub) - Template for external service integration

Integration Points

• Modified prompt_service.py to support pre/post fetch hooks
• Added plugin configuration to mcpgateway/config.py
• Updated main.py with plugin manager initialization
• Added /plugins API endpoints for management

📝 Not Yet Implemented (Future Work)

The following hooks are defined but not implemented:

• tool_pre_invoke / tool_post_invoke - For tool execution guardrails
• resource_pre_fetch / resource_post_fetch - For content filtering
• server_pre_register / server_post_register - For server validation
• auth_pre_check / auth_post_check - For custom authentication
• federation_pre_sync / federation_post_sync - For gateway federation

🧪 Testing Instructions

1. Setup

# Checkout branch
git checkout 319-plugin-framework-experimental

# Install dependencies
make install

# Configure environment
cp .env.example .env
# Ensure PLUGINS_ENABLED=true in .env

2. Basic Functionality Tests

Test Plugin Framework Disabled:

PLUGINS_ENABLED=false python -m mcpgateway
# Expected: Server starts normally, no plugin logs

Test Plugin Framework Enabled:

PLUGINS_ENABLED=true python -m mcpgateway
# Expected: "Plugin manager initialized with 1 plugins"

3. Search/Replace Plugin Test

# Create test prompt
curl -X POST http://localhost:8000/prompts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test_prompt",
    "template": "User said: {{ message }}",
    "description": "Test prompt for plugin validation"
  }'

# Test word replacement
curl -X POST http://localhost:8000/prompts/test_prompt/render \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "message": "This is crap"
    }
  }'
# Expected: "User said: This is yikes" (crap → crud → yikes)

4. Plugin Modes Test

Edit plugins/config.yaml to test different modes:

• mode: "enforce" - Blocks requests on violations
• mode: "permissive" - Logs warnings but allows requests
• mode: "disabled" - Plugin doesn't execute

5. API Endpoints Test

# List loaded plugins
curl http://localhost:8000/plugins
# Expected: JSON array of plugin details

✅ Merge Checklist

Code Quality

• All files have copyright headers and SPDX identifiers
• Code passes make lint
• No hardcoded values or secrets
• Appropriate logging levels used
• Error messages are descriptive

Functionality

• Server starts with PLUGINS_ENABLED=false (plugins fully disabled)
• Server starts with PLUGINS_ENABLED=true (plugins initialize)
• Search/replace plugin works on test_prompt
• Plugin conditions filter correctly (only affects configured prompts)
• Priority ordering works (lower numbers execute first)
• Enforcement modes work as documented
• Plugin errors don't crash the server
• API endpoints return expected data

Configuration

• .env.example includes PLUGINS_ENABLED=false
• Plugin config path is configurable
• Environment variables work in plugin configs
• Missing config file handled gracefully

Integration

• No breaking changes to existing functionality
• Existing prompts work unchanged
• No significant performance regression (<10% overhead)
• Plugin lifecycle integrated with server start/stop

Documentation

• Code includes docstrings for key classes/methods
• Configuration examples provided
• TODO markers for unimplemented hooks
• README mentions experimental plugin support

🚀 Performance Impact

# Baseline (no plugins)
PLUGINS_ENABLED=false python -m mcpgateway
time curl -X POST http://localhost:8000/prompts/test_prompt/render -d '{"arguments":{"message":"test"}}'

# With plugins
PLUGINS_ENABLED=true python -m mcpgateway
# Response time should be within 10% of baseline

⚠️ Known Limitations

1. MVP Scope - Only prompt hooks implemented, other hooks are stubs
2. No Admin UI - Plugin management via config files only
3. Limited Examples - External service plugins need implementation
4. No Hot Reload - Server restart required for config changes
5. Basic Statistics - Execution metrics not yet collected

🔧 Configuration Example

# plugins/config.yaml
plugins:
  - name: "ReplaceBadWordsPlugin"
    kind: "plugins.regex.search_replace.SearchReplacePlugin"
    description: "Replaces inappropriate words"
    version: "0.1"
    author: "MCP Context Forge Team"
    hooks: ["prompt_pre_fetch", "prompt_post_fetch"]
    tags: ["filter", "transform", "regex"]
    mode: "enforce"  # enforce | permissive | disabled
    priority: 150    # Lower = higher priority
    conditions:
      - prompts: ["test_prompt"]  # Only apply to specific prompts
        server_ids: []            # Apply to all servers
    config:
      words:
        - search: "crap"
          replace: "crud"
        - search: "crud"
          replace: "yikes"

plugin_settings:
  plugin_timeout: 30
  fail_on_plugin_error: false

🏁 Recommendation

This PR is ready to merge as an experimental/MVP feature with the understanding that:

1. Only prompt hooks are functional (tool/resource/auth hooks pending)
2. External service plugins need implementation
3. Further development will add missing functionality
4. Feature is disabled by default (PLUGINS_ENABLED=false)

The architecture is solid and provides a good foundation for the full plugin system. The implementation follows the epic design well and integrates cleanly with existing code.

📋 Sign-off Criteria

• All tests in checklist pass
• No critical bugs found
• Performance overhead < 10%
• CI/CD pipeline passes
• Documented as experimental/MVP

[crivetimihai]

🔌 Plugin Framework PR #642 - Review & Testing Guide

📊 PR Review Summary

This PR implements an MVP plugin framework for MCP Gateway, delivering the foundation for extensible request processing through pre/post hooks. The implementation focuses on prompt hooks as the initial integration point.

✅ What's Implemented (MVP Scope)

Core Framework ✅

• Plugin Base Classes - Plugin, PluginRef abstraction
• Plugin Manager - Singleton lifecycle management
• Plugin Registry - Instance management with priority ordering
• Configuration System - YAML-based with Jinja2 environment variable support
• Execution Modes - enforce, permissive, disabled per plugin
• Priority Ordering - Lower number = higher priority execution
• Conditional Execution - Filter by prompts, servers, tenants, users
• Context Management - Global and local context with state persistence

Hook Points (2 of 12 Planned)

• prompt_pre_fetch - Before prompt retrieval and rendering
• prompt_post_fetch - After prompt rendering
• tool_pre_invoke / tool_post_invoke - Not implemented
• resource_pre_fetch / resource_post_fetch - Not implemented
• server_pre_register / server_post_register - Not implemented
• auth_pre_check / auth_post_check - Not implemented
• federation_pre_sync / federation_post_sync - Not implemented

Other Future Hook Points and Features

• enumeration_pre_fetch / federation_post_fetch - Enumerations not yet implemented
• roots_pre_fetch / roots_post_fetch - Roots not yet in scope
• filter based on tags - requires [Feature Request]: Tag support with editing and validation across all APIs endpoints and UI (tags) #586

Example Plugins ✅

• SearchReplacePlugin - Text transformation (native/in-process)
• DenyListPlugin - Word blocking filter (native/in-process)
• PIIFilterPlugin - PII detection and masking with multiple strategies
• LLMGuardPlugin - Stub only, not functional
• OPA Plugin - Not implemented
• External microservice plugins - Framework present but no working examples

Integration & Management

• Modified prompt_service.py with pre/post fetch hooks
• Plugin configuration in mcpgateway/config.py
• Plugin manager initialization in main.py
• Comprehensive test suite (500+ lines)
• Plugin API endpoints (/plugins/*) - Not implemented
• Admin UI for plugin management - Not implemented
• Hot reload capability - Not implemented
• Plugin health checks - Not implemented

Configuration Features

• YAML configuration with environment variable substitution
• Plugin-specific configuration sections
• Conditional execution rules
• Priority-based execution ordering
• Runtime configuration changes - Not implemented
• Import/export of configurations - Not implemented
• JSON Schema validation - Not implemented

🔴 Critical Fixes Required Before Merge

1. Add Timeout Protection (Prevents hanging)

# File: mcpgateway/plugins/framework/manager.py
# In PluginExecutor.execute(), wrap plugin execution:

import asyncio

async def execute(self, plugins: list[PluginRef], payload: T, ...):
    for pluginref in plugins:
        try:
            # ADD THIS: Timeout wrapper
            result = await asyncio.wait_for(
                plugin_run(pluginref, payload, local_context),
                timeout=30  # 30 second timeout
            )
        except asyncio.TimeoutError:
            logger.error(f"Plugin {pluginref.name} timed out after 30s")
            if pluginref.plugin.mode == PluginMode.ENFORCE:
                violation = PluginViolation(
                    reason="Plugin timeout",
                    description=f"Plugin exceeded 30s timeout",
                    code="PLUGIN_TIMEOUT",
                    details={}
                )
                return (PluginResult[T](
                    continue_processing=False,
                    violation=violation
                ), None)
            continue  # Skip in permissive mode
        # ... rest of existing code

2. Fix Memory Leak in Context Storage

# File: mcpgateway/plugins/framework/manager.py
# Add to PluginManager class:

import time
from typing import Dict, Tuple

class PluginManager:
    def __init__(self, config: str = ""):
        # ... existing code ...
        # ADD THESE:
        self._context_store: Dict[str, Tuple[PluginContextTable, float]] = {}
        self._last_cleanup = time.time()
    
    async def _cleanup_old_contexts(self):
        """Remove contexts older than 1 hour."""
        current_time = time.time()
        if current_time - self._last_cleanup < 300:  # Cleanup every 5 min
            return
        
        expired = [
            k for k, (_, ts) in self._context_store.items()
            if current_time - ts > 3600
        ]
        for key in expired:
            del self._context_store[key]
        
        if expired:
            logger.info(f"Cleaned up {len(expired)} expired contexts")
        self._last_cleanup = current_time
    
    async def prompt_pre_fetch(self, payload: PromptPrehookPayload, ...):
        # ADD THIS at the start:
        await self._cleanup_old_contexts()
        # ... rest of existing code

3. Add Input Validation (Prevent DoS)

# File: mcpgateway/plugins/framework/manager.py
# Add at start of prompt_pre_fetch and prompt_post_fetch:

MAX_PAYLOAD_SIZE = 1_000_000  # 1MB limit

async def prompt_pre_fetch(self, payload: PromptPrehookPayload, ...):
    # ADD THIS validation:
    if payload.args:
        total_size = sum(len(str(v)) for v in payload.args.values())
        if total_size > MAX_PAYLOAD_SIZE:
            raise ValueError(f"Payload size {total_size} exceeds limit")
    
    # ... rest of existing code

🧪 Testing Instructions

Setup

# Start server with plugins enabled
export PLUGINS_ENABLED=true
make serve  # Starts on port 4444

# Create auth token
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token -u admin --secret my-test-key)

Test 1: Basic Plugin Functionality

# Create test prompt
curl -X POST http://localhost:4444/prompts \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test_prompt",
    "template": "User said: {{ user }}",
    "argument_schema": {
      "type": "object",
      "properties": {"user": {"type": "string"}},
      "required": ["user"]
    }
  }'

# Test word replacement (crap → crud → yikes)
curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "What a crap situation"}'

# Expected: "User said: What a yikes situation"

Test 2: Deny List Plugin (Blocking)

# Test with blocked word "revolutionary"
curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "This is revolutionary"}'

# Expected: HTTP 422 with error message about denied word

Test 3: PII Filter Plugin

# Test PII masking (if enabled in config)
curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "My SSN is 123-45-6789 and email is [email protected]"}'

# Expected: SSN and email should be masked (e.g., ***-**-6789, j***[email protected])

Test 4: Plugin Modes

# Edit plugins/config.yaml and change mode:
# - "enforce" → blocks on violation
# - "permissive" → logs but allows
# - "disabled" → plugin doesn't run

# Restart server after config change
make serve

# Re-run deny list test to see different behaviors

Test 5: Performance Check

# Baseline (no plugins)
PLUGINS_ENABLED=false make serve
time curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -d '{"user": "test"}'

# With plugins
PLUGINS_ENABLED=true make serve
time curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -d '{"user": "test"}'

# Performance impact should be <10%

🔧 Merge Process

# 1. Checkout PR
gh pr checkout 642

# 2. Update with latest main
git fetch origin main
git rebase origin/main
# Resolve any conflicts if needed

# 3. Run test suite
make autoflake isort black pre-commit
make doctest test smoketest lint-web flake8
make lint-commit
make check-headers
make bandit devskim
make lint target=plugins
make lint TARGET=plugins mcpgateway/plugins
make devpi-install devpi-init devpi-start devpi-setup-user devpi-upload devpi-test

# 4. Apply the 3 critical fixes above
# Edit the files and re-run test suite

# 5. Test fixes work
make serve
# Run curl tests above

# 6. Commit fixes
git add mcpgateway/plugins/framework/manager.py
git commit -m "fix: Add timeout, memory cleanup, and input validation to plugins

- Add 30s timeout for plugin execution
- Implement context cleanup to prevent memory leaks  
- Add 1MB payload size validation
- Required safety fixes per PR review"

# 7. Push changes
git push

# 8. Squash and merge
gh pr merge 642 --squash --subject "feat: Add plugin framework for extensible request processing (#642)"

✅ Merge Checklist

Critical (Must Fix):

• Timeout handling added (30s default)
• Memory leak fixed (context cleanup)
• Input validation added (1MB limit)

Testing:

• All unit tests pass (make test)
• Linting passes (make lint-web flake8)
• Server starts with PLUGINS_ENABLED=false
• Server starts with PLUGINS_ENABLED=true
• SearchReplace plugin works
• DenyList plugin blocks correctly
• Performance overhead <10%

Documentation:

• Code has proper docstrings
• SPDX headers on all files
• Configuration examples provided

📈 Post-Merge Feature Backlog

Performance Enhancements

• Add caching for compiled regex patterns in PIIDetector
• Implement LRU cache for detection results
• Add pattern compilation optimization
• Parallel execution for independent plugins

Observability & Monitoring

• Add Prometheus metrics for plugin execution
• Implement execution time tracking per plugin
• Add plugin health metrics and status endpoints
• Create dashboard for plugin monitoring
• Add detailed execution statistics API

Safety & Resilience

• Implement per-plugin rate limiting
• Add circuit breaker for failing plugins
• Implement backpressure handling
• Add plugin isolation/sandboxing
• Thread-safe registry operations

Configuration & Management

• Add JSON Schema validation for configs
• Implement hot-reload for plugin configs
• Create plugin discovery mechanism
• Add plugin versioning system
• Import/export configuration capability
• Environment-specific plugin configs

Additional Hook Implementation

• Implement tool_pre_invoke / tool_post_invoke
• Add resource_pre_fetch / resource_post_fetch
• Create auth_pre_check / auth_post_check
• Implement server_pre_register / server_post_register
• Add federation_pre_sync / federation_post_sync

External Service Integration

• Complete LLMGuard plugin implementation
• Add OPA (Open Policy Agent) plugin
• Create webhook plugin for external services
• Implement gRPC plugin interface
• Add OpenAI Moderation plugin
• Create custom AI safety filters

Developer Experience

• Create plugin development CLI tool
• Add plugin scaffolding generator
• Build plugin testing framework
• Create plugin marketplace/registry
• Add plugin development documentation
• Create example plugin templates

Admin & Management Features

• Build plugin management API endpoints
• Create web UI for plugin configuration
• Add plugin enable/disable without restart
• Implement plugin audit logging
• Add role-based plugin management
• Create plugin dependency resolution

🎯 Implementation Status vs Original Epic

Delivered in MVP

• ✅ Plugin framework foundation with base classes
• ✅ Plugin manager with lifecycle management
• ✅ Configuration system with YAML support
• ✅ Priority-based execution ordering
• ✅ Conditional execution (prompts/servers/tenants)
• ✅ Three execution modes (enforce/permissive/disabled)
• ✅ Native plugin examples (PII, DenyList, SearchReplace)
• ✅ Prompt hooks implementation

Not Yet Implemented

• ❌ Tool, resource, server, auth, federation hooks
• ❌ External microservice plugins (LLMGuard, OPA)
• ❌ Plugin API endpoints and management UI
• ❌ Hot reload capability
• ❌ Plugin health checks and monitoring
• ❌ HashiCorp Vault integration for state
• ❌ Plugin marketplace/registry
• ❌ Import/export of configurations
• ❌ Update version.py and mcpgateway --version with plugin information

Potential issues:

Check for race condition in comments below.

🚀 Final Verdict

APPROVED FOR MERGE after applying the 3 critical fixes. This MVP successfully delivers the plugin framework foundation with prompt hooks as the initial integration point. The architecture is extensible and well-tested, providing a solid base for future hook implementations and external service integrations.

The implementation follows clean architecture principles with proper separation of concerns, comprehensive error handling, and extensive test coverage. The disabled-by-default approach ensures zero impact on existing deployments.

---

I will apply the 3 fixes and push the changes. Once done, we can proceed with the squash and merge.

[crivetimihai]

Testing regex filtering

curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "What a crap situation"}'

{"messages":[{"role":"user","content":{"type":"text","text":"User said: What a yikes situation"}}],"description":null}

Testing blocking:

curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "This is revolutionary"}'

{"message":"Prompt execution arguments contains HTML tags that may cause security issues","details":"Pre prompting fetch blocked by plugin DenyListPlugin: deny - Prompt not allowed (A deny word was found in the prompt)"}

Testing PII Filtering

curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "My SSN is 123-45-6789 and email is [email protected]"}'

{"messages":[{"role":"user","content":{"type":"text","text":"User said: My SSN is [PII_REDACTED]-**-6789DACTED]-***-***-***-***-6789 and email is j******@example.com"}}],"description":null}

[crivetimihai]

There might be a race condition here:

WARNI [plugins.deny_filter.deny] Deny word detected in prompt argument 'user'
WARNI [mcpgateway.plugins.framework.manager] Plugin DenyListPlugin blocked request in enforce mode
ERROR [mcpgateway] Could not retrieve prompt test_prompt: Pre prompting fetch blocked by plugin DenyListPlugin: deny - Prompt not allowed (A deny word was found in the prompt)
127.0.0.1:57066 - "POST /prompts/test_prompt HTTP/1.1" 422
WARNI [plugins.deny_filter.deny] Deny word detected in prompt argument 'user'
WARNI [mcpgateway.plugins.framework.manager] Plugin DenyListPlugin blocked request in enforce mode
ERROR [mcpgateway] Could not retrieve prompt test_prompt: Pre prompting fetch blocked by plugin DenyListPlugin: deny - Prompt not allowed (A deny word was found in the prompt)


{"messages":[{"role":"user","content":{"type":"text","text":"User said: What a yikes situation"}}],"description":null}%                                                                     ➜  mcp-context-forge git:(319-plugin-framework) curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "What a crap situation"}'
{"messages":[{"role":"user","content":{"type":"text","text":"User said: What a yikes situation"}}],"description":null}%                                                                     ➜  mcp-context-forge git:(319-plugin-framework) curl -X POST http://localhost:4444/prompts/test_prompt \
  -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "What a crap situation"}'
curl: (52) Empty reply from server

[crivetimihai]

Crated #673 to track next steps.

[crivetimihai]

Ready to merge.

[MohanLaksh]

Feature Validation:

Tested -
Word Replacement,
Deny List Plugin,
PII Filter Plugin

Working well.

PR Test summary:

make serve - pass
make test - pass (80%, === === 1190 passed, 10 skipped, 50 warnings in 38.99s ===)
make autoflake isort black flake8 - pass
make pylint - pass (Your code has been rated at 10.00/10 )
make smoketest - ✅ Smoketest passed!
make doctest - pass (57%, 383 passed, 8 skipped in 12.10s)