JSON Schema Validator MCP Server

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

🚀 Features

• JSON Schema Draft 2020-12 Support: Full compliance with the latest JSON Schema specification

• External Reference Resolution: Automatic resolution of external schema references via HTTP/HTTPS, database, or local files

• Dual Server Architecture:

  • MCP Server for stdio communication with AI assistants

  • SSE Server for web clients with real-time streaming

• Schema Management: Complete CRUD operations for schema collections

• Data Storage Flexibility: PostgreSQL database with local file fallback

• Schema Generation: Automatic JSON Schema generation from sample JSON data

• Docker Support: Containerized deployment ready

Related MCP server: BigQuery Analysis MCP Server

🏗️ Architecture

Core Components

• MCP Server (mcp_server.py): Primary server for AI assistant integration

• SSE Server (sse_server.py): HTTP server with Server-Sent Events for web clients

• Validation Engine (tools/JSONSchemaValidator.py): JSON Schema Draft 2020-12 validator

• Data Manager (utils/DataManager.py): Multi-source data resolution with fallback strategy

• Schema Generator (utils/SchemaGenerator.py): Automatic schema generation from JSON data

Data Resolution Strategy

1. PostgreSQL Database (schemas/data_storage tables)

2. Local Files (final fallback)

📦 Installation

Prerequisites

• Python 3.8+

• PostgreSQL (optional, for database storage)

Quick Start

1. Clone the repository

   git clone https://github.com/EienWolf/jsonshema_mcp.git
   cd jsonschema_mcp

2. Install dependencies

   pip install -r requirements.txt

3. Run the MCP server

   python mcp_server.py

4. Run the SSE server (optional)

   python sse_server.py

🔧 Configuration

Environment Variables

Create a .env file:

# PostgreSQL Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=jsonschema_mcp
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password

# Schema Management
POSTGRES_AUTO_CREATE_SCHEMA=true   # Auto-create tables if missing
POSTGRES_AUTO_RESET=false          # WARNING: Drops all data!

🛠️ Available MCP Tools

Validation Tools

• validate_json_schema: Direct validation with provided schema

• validate_json_from_collections: Validation using stored schemas

• get_validation_info: Validator capabilities and information

Schema Management Tools

• add_update_schema: Add or update schemas in collections

• delete_schema: Delete schemas from collections

• get_schema: Retrieve schema content

• list_schemas: List all available schemas

• generate_schema: Generate schema from JSON data

🐳 Docker Deployment

Build and Run

# Build image
docker build -t jsonschema-mcp-server:1.0.0 .

# Run container
docker run -i jsonschema-mcp-server:1.0.0

# Run with persistent schema storage
docker run -i -v ./schemas:/app/.schemas jsonschema-mcp-server:1.0.0

Docker Features

• Multi-stage build optimization

• Non-root user security

• Health check monitoring

• Volume support for data persistence

• Automatic dependency management

🤖 MCP Server Configuration

Claude Desktop Integration

Method 1: Direct Python Execution

Add to your Claude Desktop configuration file:

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"
      }
    }
  }
}

Linux/macOS Example:

{
  "mcpServers": {
    "jsonschema-validator": {
      "command": "python3",
      "args": ["/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"
      }
    }
  }
}

Method 2: Docker Container

{
  "mcpServers": {
    "jsonschema-validator": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "./schemas:/app/.schemas",
        "-e", "POSTGRES_HOST=host.docker.internal",
        "-e", "POSTGRES_PORT=5432",
        "-e", "POSTGRES_DATABASE=jsonschema_mcp",
        "-e", "POSTGRES_USER=your_username",
        "-e", "POSTGRES_PASSWORD=your_password",
        "jsonschema-mcp-server:1.0.0"
      ]
    }
  }
}

GitHub Copilot Integration

Method 1: Direct Python Execution

Create or update your MCP configuration file:

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"
      }
    }
  }
}

Linux/macOS Example:

{
  "servers": {
    "jsonschema-validator": {
      "command": "python3",
      "args": ["/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"
      }
    }
  }
}

Method 2: Docker Container

{
  "servers": {
    "jsonschema-validator": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "./schemas:/app/.schemas",
        "-e", "POSTGRES_HOST=host.docker.internal",
        "-e", "POSTGRES_PORT=5432",
        "-e", "POSTGRES_DATABASE=jsonschema_mcp",
        "-e", "POSTGRES_USER=your_username", 
        "-e", "POSTGRES_PASSWORD=your_password",
        "jsonschema-mcp-server:1.0.0"
      ]
    }
  }
}

Configuration Notes

1. Database Configuration:

   • Environment variables are optional

   • Server automatically falls back to local file storage if database is unavailable

   • For file-only mode, omit all POSTGRES_* environment variables

2. Path Requirements:

   • Use absolute paths for mcp_server.py

   • Ensure Python is in your system PATH

   • For Docker, ensure the image is built: docker build -t jsonschema-mcp-server:1.0.0 .

3. Permissions:

   • Ensure the server has write permissions to the schemas directory

   • For Docker on Windows, use WSL2 backend for better volume mounting

4. Testing Configuration:

   # Test direct execution
   python mcp_server.py
   
   # Test Docker execution  
   docker run -i jsonschema-mcp-server:1.0.0

5. File-Only Configuration (No Database):

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

🌐 Web Client

The repository includes a complete web client (client_example.html) demonstrating:

• Real-time validation with Server-Sent Events

• Schema management interface

• Interactive testing environment

• Progress tracking and error reporting

🔒 Security Features

• Input Validation: Schema ID format validation with Linux path requirements

• Path Security: Prevention of directory traversal attacks

• Confirmation Requirements: Explicit confirmation for destructive operations

• Error Handling: Detailed error messages without sensitive information exposure

• Non-root Execution: Docker containers run as non-privileged user

📋 Requirements

• jsonschema>=4.25.0 - JSON Schema validation

• mcp>=1.0.0 - Model Context Protocol

• psycopg2-binary>=2.9.0 - PostgreSQL adapter

• fastapi>=0.104.0 - SSE server framework

• uvicorn>=0.24.0 - ASGI server

• pydantic>=2.5.0 - Data validation

• ruff>=0.8.0 - Code linting and formatting

🆘 Troubleshooting

Common Issues

1. Database Connection Failed

   • Check PostgreSQL is running

   • Verify credentials in .env

   • Server falls back to file storage automatically

2. Permission Denied

   • Ensure write permissions for .schemas directory

   • Check Docker volume mounting

3. Schema Not Found

   • Verify schema ID format (must end with .json)

   • Check schema exists with list_schemas tool

🗺️ Roadmap

See our ROADMAP.md for planned features and future development directions, including DXT package integration, enhanced schema generation, and AI-powered capabilities.

📄 License

This project is licensed under a Custom Non-Commercial License. See the LICENSE file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol (MCP) specification

• Uses the jsonschema library for validation

• Inspired by modern API design patterns

• Designed for integration with AI assistants

📞 Support

For issues, questions, or contributions:

1. Check the troubleshooting section above

2. Review existing issues and documentation

3. Create a detailed issue report with:

   • Error messages

   • Steps to reproduce

   • Environment details

   • Expected vs actual behavior

Made with ❤️ for the AI and developer community