MCP JSON Schema Validator

A comprehensive JSON Schema validation server implementing the Model Context Protocol (MCP) with support for JSON Schema Draft 2020-12, external references, schema management, and real-time streaming validation.

Key Features

• Full JSON Schema Draft 2020-12 Support: Complete compliance with the latest JSON Schema specification including all validation keywords and formats
• External Reference Resolution: Automatic resolution of external schema references via HTTP/HTTPS, PostgreSQL database, or local files with intelligent fallback strategy
• Schema Management: Complete CRUD operations for schema collections with validation, versioning, and organized storage
• Dual Server Architecture:
  • MCP Server for stdio communication with AI assistants (Claude, Copilot)
  • SSE Server for web clients with real-time streaming validation
• Multi-Source Data Storage: PostgreSQL database with automatic local file fallback for maximum reliability
• Schema Generation: Intelligent JSON Schema generation from sample JSON data with configurable null handling
• Docker Ready: Containerized deployment with security best practices and health monitoring
• Web Client: Complete web interface with real-time validation and schema management

Tools Provided

1. validate_json_schema

Action: Validates JSON data against a provided JSON Schema with detailed error reporting.

Parameters:

• json_data (object|string): JSON data to validate (object or JSON string)
• json_schema (object|string): JSON Schema for validation (object or JSON string)

Returns: Validation result with success status, error count, and detailed error messages with paths.

Example: Validate user data against schema

{
  "json_data": {"name": "John", "age": "invalid"},
  "json_schema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "age": {"type": "number"}
    },
    "required": ["name", "age"]
  }
}

Expected Output: Detailed validation report showing the age field type error with exact path location.

2. validate_json_from_collections

Action: Validates JSON data against a schema stored in the .schemas collection by schema ID.

Parameters:

• json_data (object|string): JSON data to validate
• schema_id (string): Schema identifier from collection (e.g., "user.json", "api/v1/user.json")

Returns: Validation result with schema information and detailed error reporting.

Example: Validate against stored schema

{
  "json_data": {"username": "john", "email": "invalid-email"},
  "schema_id": "user/profile.json"
}

3. get_validation_info

Action: Retrieves information about validator capabilities, supported formats, and system status.

Parameters: None (empty object {})

Returns: Comprehensive validator information including JSON Schema version, supported features, and data sources.

4. add_update_schema

Action: Adds or updates JSON schemas in the .schemas collection with comprehensive validation.

Parameters:

• schema_id (string): Schema identifier following Linux path format (must end with .json)
• schema_content (string): Valid JSON Schema as string
• update_if_exists (boolean, optional): Whether to update existing schemas (default: false)

Security: Schema ID validation prevents directory traversal attacks and enforces naming conventions.

Example: Add user profile schema

{
  "schema_id": "user/profile.json",
  "schema_content": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}",
  "update_if_exists": false
}

5. delete_schema

Action: Safely deletes JSON schemas from the .schemas collection with confirmation requirement.

Parameters:

• schema_id (string): Schema identifier to delete
• confirm_deletion (boolean, required): Must be true to proceed (safety measure)

Security: Requires explicit confirmation to prevent accidental deletions.

6. get_schema

Action: Retrieves raw JSON schema content from the .schemas collection.

Parameters:

• schema_id (string): Schema identifier to retrieve

Returns: Pure JSON schema content as stored, without additional metadata.

7. list_schemas

Action: Lists all available schema IDs from the .schemas collection with metadata.

Parameters: None (empty object {})

Returns: Formatted list of all schemas with count, source information, and helpful guidance.

8. generate_schema

Action: Generates JSON Schema from sample JSON data and saves it to the collection.

Parameters:

• schema_id (string): Identifier for the generated schema
• json_data (object|string): Sample JSON data for schema generation
• null_handling (string, optional): Strategy for null values ("allow", "ignore", "strict")

Returns: Generated schema details with property analysis and save confirmation.

Example: Generate schema from user data

{
  "schema_id": "generated_user.json",
  "json_data": {
    "name": "John Doe",
    "age": 30,
    "preferences": {"theme": "dark"},
    "tags": ["developer"],
    "address": null
  },
  "null_handling": "allow"
}

Configuration

Quick Setup with Python

Prerequisites: Python 3.8+, PostgreSQL (optional)

# Clone and install
git clone https://github.com/EienWolf/jsonshema_mcp.git
cd jsonschema_mcp
pip install -r requirements.txt

# Run MCP server
python mcp_server.py

# Run web server (optional)
python sse_server.py

Claude Desktop Configuration

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jsonschema-validator": {
      "command": "python",
      "args": ["C:\\path\\to\\jsonschema_mcp\\mcp_server.py"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "jsonschema_mcp",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password"
      }
    }
  }
}

GitHub Copilot Configuration

File: ~/.mcp/config.json (Linux/macOS) or %USERPROFILE%\.mcp\config.json (Windows)

{
  "servers": {
    "jsonschema-validator": {
      "command": "python",
      "args": ["C:\\path\\to\\jsonschema_mcp\\mcp_server.py"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "jsonschema_mcp",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password"
      }
    }
  }
}

Docker Configuration

# Build and run
docker build -t jsonschema-mcp-server:1.0.0 .
docker run -i -v ./schemas:/app/.schemas jsonschema-mcp-server:1.0.0

Docker MCP Configuration:

{
  "mcpServers": {
    "jsonschema-validator": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "./schemas:/app/.schemas",
        "-e", "POSTGRES_HOST=host.docker.internal",
        "jsonschema-mcp-server:1.0.0"
      ]
    }
  }
}

Database Configuration (Optional)

Create .env file:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=jsonschema_mcp
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_AUTO_CREATE_SCHEMA=true

Note: Server automatically falls back to local file storage if database is unavailable.

File-Only Mode

For simplified setup without database:

{
  "mcpServers": {
    "jsonschema-validator": {
      "command": "python",
      "args": ["C:\\path\\to\\jsonschema_mcp\\mcp_server.py"]
    }
  }
}

Security Features

• Input Validation: Comprehensive schema ID format validation with Linux path requirements
• Path Security: Prevention of directory traversal attacks and malicious file access
• Confirmation Requirements: Explicit confirmation for destructive operations (delete)
• Error Handling: Detailed error messages without sensitive information exposure
• Non-root Execution: Docker containers run as non-privileged user
• Data Isolation: Schema collections isolated from system files

Requirements

• jsonschema>=4.25.0 - JSON Schema validation engine
• mcp>=1.0.0 - Model Context Protocol implementation
• psycopg2-binary>=2.9.0 - PostgreSQL database adapter
• fastapi>=0.104.0 - SSE server framework
• uvicorn>=0.24.0 - ASGI server for web interface
• pydantic>=2.5.0 - Data validation and serialization
• ruff>=0.8.0 - Code linting and formatting

Architecture

• Modular Handler System: Separate handlers for validation and schema management
• Multi-Source Data Resolution: HTTP → Database → Local Files fallback strategy
• Caching System: Intelligent schema caching for performance
• Error Recovery: Graceful fallback when external resources are unavailable
• Streaming Support: Real-time validation with Server-Sent Events
• Connection Pooling: Efficient database connections with automatic cleanup

License

Custom Non-Commercial License. See LICENSE file for details.

Support & Documentation

• Full Documentation: README.md
• Future Plans: ROADMAP.md
• Web Demo: client_example.html for interactive testing
• GitHub Issues: Report bugs and request features

Built for the AI and developer community with ❤️