Plugins now support resources pre/post hooks (#719)

* Plugins now support resources pre/post

Signed-off-by: Mihai Criveti <[email protected]>

* Plugins now support resources pre/post

Signed-off-by: Mihai Criveti <[email protected]>

* Plugins now support resources pre/post

Signed-off-by: Mihai Criveti <[email protected]>

* Plugins now support resources pre/post

Signed-off-by: Mihai Criveti <[email protected]>

* Plugins now support resources pre/post

Signed-off-by: Mihai Criveti <[email protected]>

* Plugins now support resources pre/post

Signed-off-by: Mihai Criveti <[email protected]>

---------

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

docs/docs/using/plugins/index.md

@@ -1,7 +1,7 @@
 # Plugin Framework
 
 !!! warning "Experimental Feature"
-    The plugin framework is currently in **MVP stage** and marked as experimental. Only prompt hooks (`prompt_pre_fetch` and `prompt_post_fetch`) are implemented. Additional hooks for tools, resources, authentication, and server registration are planned for future releases.
+    The plugin framework is currently in **MVP stage** and marked as experimental. Prompt, tool, and resource hooks are implemented. Additional hooks for authentication and server registration are planned for future releases.
 
 ## Overview
 
@@ -94,7 +94,7 @@ are defined as follows:
 | **description** | The description of the plugin configuration. | A plugin for replacing bad words. |
 | **version** | The version of the plugin configuration. | 0.1 |
 | **author** | The team that wrote the plugin. | MCP Context Forge |
-| **hooks** | A list of hooks for which the plugin will be executed. Supported hooks: "prompt_pre_fetch", "prompt_post_fetch", "tool_pre_invoke", "tool_post_invoke"  | ["prompt_pre_fetch", "prompt_post_fetch", "tool_pre_invoke", "tool_post_invoke"] |
+| **hooks** | A list of hooks for which the plugin will be executed. Supported hooks: "prompt_pre_fetch", "prompt_post_fetch", "tool_pre_invoke", "tool_post_invoke", "resource_pre_fetch", "resource_post_fetch"  | ["prompt_pre_fetch", "prompt_post_fetch", "tool_pre_invoke", "tool_post_invoke", "resource_pre_fetch", "resource_post_fetch"] |
 | **tags** | Descriptive keywords that make the configuration searchable. | ["security", "filter"] |
 | **mode** | Mode of operation of the plugin. - enforce (stops during a violation), permissive (audits a violation but doesn't stop), disabled (disabled) | permissive |
 | **priority** | The priority in which the plugin will run - 0 is higher priority | 100 |
@@ -152,6 +152,7 @@ Users may only want plugins to be invoked on specific servers, tools, and prompt
 | **server_ids** | The list of MCP servers on which the plugin will trigger |
 | **tools** | The list of tools on which the plugin will be applied. |
 | **prompts** | The list of prompts on which the plugin will be applied. |
+| **resources** | The list of resource URIs on which the plugin will be applied. |
 | **user_patterns** | The list of users on which the plugin will be applied. |
 | **content_types** | The list of content types on which the plugin will trigger. |
 
@@ -165,6 +166,8 @@ Currently implemented hooks:
 | `prompt_post_fetch` | After prompt rendering | Filter/transform rendered prompts |
 | `tool_pre_invoke` | Before tool invocation | Validate/modify tool arguments, block dangerous operations |
 | `tool_post_invoke` | After tool execution | Filter/transform tool results, audit tool usage |
+| `resource_pre_fetch` | Before resource fetching | Validate URIs, check protocols, add metadata |
+| `resource_post_fetch` | After resource fetching | Filter content, redact sensitive data, validate size |
 
 ### Tool Hooks Details
 
@@ -180,9 +183,23 @@ Example use cases:
 - Input validation and sanitization
 - Output filtering and transformation
 
+### Resource Hooks Details
+
+The resource hooks enable plugins to intercept and modify resource fetching:
+
+- **`resource_pre_fetch`**: Receives the resource URI and metadata before fetching. Can modify the URI, add metadata, or block the fetch entirely.
+- **`resource_post_fetch`**: Receives the resource content after fetching. Can modify the content, redact sensitive information, or block it from being returned.
+
+Example use cases:
+- Protocol validation (block non-HTTPS resources)
+- Domain blocklisting/allowlisting
+- Content size limiting
+- Sensitive data redaction
+- Content transformation and filtering
+- Resource caching metadata
+
 Planned hooks (not yet implemented):
 
-- `resource_pre_fetch` / `resource_post_fetch` - Resource content filtering
 - `server_pre_register` / `server_post_register` - Server validation
 - `auth_pre_check` / `auth_post_check` - Custom authentication
 - `federation_pre_sync` / `federation_post_sync` - Gateway federation
@@ -203,7 +220,11 @@ from mcpgateway.plugins.framework.plugin_types import (
     ToolPreInvokePayload,
     ToolPreInvokeResult,
     ToolPostInvokePayload,
-    ToolPostInvokeResult
+    ToolPostInvokeResult,
+    ResourcePreFetchPayload,
+    ResourcePreFetchResult,
+    ResourcePostFetchPayload,
+    ResourcePostFetchResult
 )
 
 class MyPlugin(Plugin):
@@ -326,6 +347,62 @@ class MyPlugin(Plugin):
 
         return ToolPostInvokeResult()
 
+    async def resource_pre_fetch(
+        self,
+        payload: ResourcePreFetchPayload,
+        context: PluginContext
+    ) -> ResourcePreFetchResult:
+        """Process resource before fetching."""
+
+        # Access resource URI and metadata
+        uri = payload.uri
+        metadata = payload.metadata
+
+        # Example: Block certain protocols
+        from urllib.parse import urlparse
+        parsed = urlparse(uri)
+        if parsed.scheme not in ["http", "https", "file"]:
+            return ResourcePreFetchResult(
+                continue_processing=False,
+                violation=PluginViolation(
+                    plugin_name=self.name,
+                    description=f"Protocol {parsed.scheme} not allowed",
+                    violation_code="PROTOCOL_BLOCKED",
+                    details={"uri": uri, "protocol": parsed.scheme}
+                )
+            )
+
+        # Example: Add metadata
+        metadata["validated_by"] = self.name
+        return ResourcePreFetchResult(
+            modified_payload=ResourcePreFetchPayload(uri, metadata)
+        )
+
+    async def resource_post_fetch(
+        self,
+        payload: ResourcePostFetchPayload,
+        context: PluginContext
+    ) -> ResourcePostFetchResult:
+        """Process resource after fetching."""
+
+        # Access resource content
+        uri = payload.uri
+        content = payload.content
+
+        # Example: Redact sensitive patterns from text content
+        if hasattr(content, 'text') and content.text:
+            # Redact email addresses
+            import re
+            content.text = re.sub(
+                r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
+                '[EMAIL_REDACTED]',
+                content.text
+            )
+
+        return ResourcePostFetchResult(
+            modified_payload=ResourcePostFetchPayload(uri, content)
+        )
+
     async def shutdown(self):
         """Cleanup when plugin shuts down."""
         # Close connections, save state, etc.

mcpgateway/main.py

@@ -32,6 +32,7 @@
 import time
 from typing import Any, AsyncIterator, Dict, List, Optional, Union
 from urllib.parse import urlparse, urlunparse
+import uuid
 
 # Third-Party
 from fastapi import APIRouter, Body, Depends, FastAPI, HTTPException, Request, status, WebSocket, WebSocketDisconnect
@@ -1499,12 +1500,13 @@ async def create_resource(
 
 
 @resource_router.get("/{uri:path}")
-async def read_resource(uri: str, db: Session = Depends(get_db), user: str = Depends(require_auth)) -> ResourceContent:
+async def read_resource(uri: str, request: Request, db: Session = Depends(get_db), user: str = Depends(require_auth)) -> ResourceContent:
     """
-    Read a resource by its URI.
+    Read a resource by its URI with plugin support.
 
     Args:
         uri (str): URI of the resource.
+        request (Request): FastAPI request object for context.
         db (Session): Database session.
         user (str): Authenticated user.
 
@@ -1514,14 +1516,23 @@ async def read_resource(uri: str, db: Session = Depends(get_db), user: str = Dep
     Raises:
         HTTPException: If the resource cannot be found or read.
     """
-    logger.debug(f"User {user} requested resource with URI {uri}")
+    # Get request ID from headers or generate one
+    request_id = request.headers.get("X-Request-ID", str(uuid.uuid4()))
+    server_id = request.headers.get("X-Server-ID")
+
+    logger.debug(f"User {user} requested resource with URI {uri} (request_id: {request_id})")
+
+    # Check cache
     if cached := resource_cache.get(uri):
         return cached
+
     try:
-        content: ResourceContent = await resource_service.read_resource(db, uri)
+        # Call service with context for plugin support
+        content: ResourceContent = await resource_service.read_resource(db, uri, request_id=request_id, user=user, server_id=server_id)
     except (ResourceNotFoundError, ResourceError) as exc:
         # Translate to FastAPI HTTP error
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+
     resource_cache.set(uri, content)
     return content
 
@@ -1759,10 +1770,12 @@ async def get_prompt(
     except Exception as ex:
         error_message = str(ex)
         logger.error(f"Could not retrieve prompt {name}: {ex}")
-        if isinstance(ex, (ValueError, PromptError)):
-            result = JSONResponse(content={"message": "Prompt execution arguments contains HTML tags that may cause security issues"}, status_code=422)
-        elif isinstance(ex, PluginViolationError):
-            result = JSONResponse(content={"message": "Prompt execution arguments contains HTML tags that may cause security issues", "details": ex.message}, status_code=422)
+        if isinstance(ex, PluginViolationError):
+            # Return the actual plugin violation message
+            result = JSONResponse(content={"message": ex.message, "details": str(ex.violation) if hasattr(ex, "violation") else None}, status_code=422)
+        elif isinstance(ex, (ValueError, PromptError)):
+            # Return the actual error message
+            result = JSONResponse(content={"message": str(ex)}, status_code=422)
         else:
             raise
 

mcpgateway/plugins/framework/base.py

@@ -3,7 +3,7 @@
 
 Copyright 2025
 SPDX-License-Identifier: Apache-2.0
-Authors: Teryl Taylor
+Authors: Teryl Taylor, Mihai Criveti
 
 This module implements the base plugin object.
 It supports pre and post hooks AI safety, security and business processing
@@ -210,6 +210,56 @@ async def tool_post_invoke(self, payload: ToolPostInvokePayload, context: Plugin
         # Default pass-through implementation
         return ToolPostInvokeResult(continue_processing=True, modified_payload=payload)
 
+    async def resource_pre_fetch(self, payload, context):
+        """Plugin hook run before a resource is fetched.
+
+        Args:
+            payload: The resource payload to be analyzed.
+            context: Contextual information about the hook call.
+
+        Returns:
+            ResourcePreFetchResult with processing status and modified payload.
+
+        Examples:
+            >>> from mcpgateway.plugins.framework.plugin_types import ResourcePreFetchPayload, PluginContext, GlobalContext
+            >>> payload = ResourcePreFetchPayload("file:///data.txt", {"cache": True})
+            >>> context = PluginContext(GlobalContext(request_id="123"))
+            >>> # In async context:
+            >>> # result = await plugin.resource_pre_fetch(payload, context)
+        """
+        # Import here to avoid circular dependency
+        # First-Party
+        from mcpgateway.plugins.framework.plugin_types import ResourcePreFetchResult
+
+        # Default pass-through implementation
+        return ResourcePreFetchResult(continue_processing=True, modified_payload=payload)
+
+    async def resource_post_fetch(self, payload, context):
+        """Plugin hook run after a resource is fetched.
+
+        Args:
+            payload: The resource content payload to be analyzed.
+            context: Contextual information about the hook call.
+
+        Returns:
+            ResourcePostFetchResult with processing status and modified content.
+
+        Examples:
+            >>> from mcpgateway.plugins.framework.plugin_types import ResourcePostFetchPayload, PluginContext, GlobalContext
+            >>> from mcpgateway.models import ResourceContent
+            >>> content = ResourceContent(type="resource", uri="file:///data.txt", text="Data")
+            >>> payload = ResourcePostFetchPayload("file:///data.txt", content)
+            >>> context = PluginContext(GlobalContext(request_id="123"))
+            >>> # In async context:
+            >>> # result = await plugin.resource_post_fetch(payload, context)
+        """
+        # Import here to avoid circular dependency
+        # First-Party
+        from mcpgateway.plugins.framework.plugin_types import ResourcePostFetchResult
+
+        # Default pass-through implementation
+        return ResourcePostFetchResult(continue_processing=True, modified_payload=payload)
+
     async def shutdown(self) -> None:
         """Plugin cleanup code."""
 

mcpgateway/plugins/framework/loader/config.py

@@ -3,7 +3,7 @@
 
 Copyright 2025
 SPDX-License-Identifier: Apache-2.0
-Authors: Teryl Taylor
+Authors: Teryl Taylor, Mihai Criveti
 
 This module loads configurations for plugins.
 """

mcpgateway/plugins/framework/loader/plugin.py

@@ -3,7 +3,7 @@
 
 Copyright 2025
 SPDX-License-Identifier: Apache-2.0
-Authors: Teryl Taylor
+Authors: Teryl Taylor, Mihai Criveti
 
 This module implements the plugin loader.
 """