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 ❤️