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

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