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

PostgreSQL Database (schemas/data_storage tables)
Local Files (final fallback)

📦 Installation

Prerequisites

Python 3.8+
PostgreSQL (optional, for database storage)

Quick Start

Clone the repository

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

Install dependencies
```
pip install -r requirements.txt
```
Run the MCP server
```
python mcp_server.py
```
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

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
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 .
Permissions:
- Ensure the server has write permissions to the schemas directory
- For Docker on Windows, use WSL2 backend for better volume mounting

Testing Configuration:

# Test direct execution
python mcp_server.py

# Test Docker execution  
docker run -i jsonschema-mcp-server:1.0.0

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

Database Connection Failed
- Check PostgreSQL is running
- Verify credentials in .env
- Server falls back to file storage automatically
Permission Denied
- Ensure write permissions for .schemas directory
- Check Docker volume mounting
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:

Check the troubleshooting section above
Review existing issues and documentation
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