Overview

Create a JSON Schema Validator Plugin that validates tool arguments against predefined JSON schemas to ensure data integrity and type safety.

Plugin Requirements

Plugin Details

• Name: JSONSchemaValidatorPlugin
• Type: Self-contained (native) plugin
• File Location: plugins/json_schema_validator/
• Complexity: Low

Functionality

• Validate tool arguments against JSON schemas before execution
• Support multiple schema formats (JSON Schema Draft 7, OpenAPI schemas)
• Configurable schema sources (inline, file-based, remote URLs)
• Detailed validation error reporting
• Schema caching for performance

Hook Integration

• Primary Hook: tool_pre_invoke
• Purpose: Validate tool arguments before execution
• Behavior: Block invalid requests or transform them based on configuration

Configuration Schema

plugins:
  - name: "JSONSchemaValidator"
    kind: "plugins.json_schema_validator.validator.JSONSchemaValidatorPlugin"
    description: "Validates tool arguments against JSON schemas"
    version: "0.1.0"
    hooks: ["tool_pre_invoke"]
    mode: "enforce"  # enforce | permissive | disabled
    priority: 30
    conditions:
      - tools: ["database_query", "file_upload", "api_call"]
    config:
      # Schema definitions
      schemas:
        database_query:
          type: "object"
          properties:
            query:
              type: "string"
              pattern: "^SELECT|INSERT|UPDATE|DELETE"
            params:
              type: "array"
              maxItems: 100
          required: ["query"]
        file_upload:
          type: "object"
          properties:
            filename:
              type: "string"
              pattern: "^[a-zA-Z0-9._-]+$"
            content_type:
              type: "string"
              enum: ["image/jpeg", "image/png", "text/plain"]
            size:
              type: "integer"
              maximum: 10485760  # 10MB
          required: ["filename", "content_type"]
      
      # Schema loading options
      schema_sources:
        - type: "file"
          path: "schemas/tools/"
        - type: "url"
          url: "https://api.company.com/schemas/"
          
      # Validation options
      strict_mode: true
      allow_additional_properties: false
      coerce_types: false  # Auto-convert compatible types
      cache_schemas: true
      cache_ttl_seconds: 3600

Implementation Requirements

File Structure

plugins/json_schema_validator/
├── __init__.py
├── validator.py              # Main plugin class
├── schema_loader.py          # Schema loading utilities  
├── plugin-manifest.yaml     # Plugin metadata
├── README.md                # Usage documentation
└── schemas/                 # Example schema files
    ├── database_query.json
    ├── file_upload.json
    └── api_call.json

Core Features

1. Schema Validation

   • JSON Schema Draft 7 support
   • Custom validation rules
   • Nested object validation
   • Array validation with size limits

2. Schema Loading

   • Inline schema definitions in config
   • File-based schema loading
   • Remote schema fetching with caching
   • Hot-reload schema updates

3. Error Handling

   • Detailed validation error messages
   • Field-level error reporting
   • Suggestion engine for common mistakes
   • Graceful degradation options

4. Performance Optimizations

   • Schema compilation and caching
   • Lazy schema loading
   • Validation result caching
   • Minimal memory footprint

Usage Examples

Basic Tool Validation

# Tool call with valid arguments
{
    "tool": "database_query",
    "arguments": {
        "query": "SELECT * FROM users WHERE id = ?",
        "params": [123]
    }
}
# Result: Validation passes, tool executes normally

# Tool call with invalid arguments  
{
    "tool": "database_query",
    "arguments": {
        "query": "DROP TABLE users;",  # Invalid pattern
        "params": ["too", "many", "params", ...] # Exceeds maxItems
    }
}
# Result: Validation fails, request blocked with detailed error

File Upload Validation

{
    "tool": "file_upload",
    "arguments": {
        "filename": "document.pdf",        # Invalid: PDF not allowed
        "content_type": "application/pdf", # Not in enum
        "size": 20971520                  # Exceeds maximum size
    }
}
# Result: Multiple validation errors reported

Error Response Format

{
    "error": "VALIDATION_FAILED",
    "message": "Tool arguments failed schema validation",
    "details": {
        "tool": "database_query",
        "violations": [
            {
                "field": "query",
                "message": "String does not match pattern '^SELECT|INSERT|UPDATE|DELETE'",
                "value": "DROP TABLE users;",
                "constraint": "pattern"
            },
            {
                "field": "params",
                "message": "Array exceeds maximum length of 100",
                "value": [...],
                "constraint": "maxItems"
            }
        ]
    }
}

Testing Requirements

• Unit tests for all validation scenarios
• Schema loading tests (file, URL, inline)
• Performance tests with large schemas
• Error handling and edge case tests
• Integration tests with real MCP tools

Documentation Requirements

• Plugin usage guide with examples
• Schema definition best practices
• Performance tuning recommendations
• Troubleshooting common validation errors

Acceptance Criteria

• Plugin implements JSONSchemaValidatorPlugin class
• Supports JSON Schema Draft 7 validation
• Configurable schema sources (inline, file, URL)
• Comprehensive error reporting with field-level details
• Schema caching for performance
• Plugin manifest and documentation created
• Unit tests with >90% coverage
• Integration tests with sample tools
• Performance benchmarks documented

Priority

Medium - Enables data integrity and type safety for enterprise deployments

Dependencies

• jsonschema Python library
• Plugin framework infrastructure
• HTTP client for remote schema fetching