Skip to main content
Glama

JSON Schema Validator MCP Server

by EienWolf
  • Apple
  • Linux

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

Related MCP Servers

  • -
    security
    F
    license
    -
    quality
    A server that enables executing and validating SQL queries against Google BigQuery with safety features that prevent data modifications and excessive processing.
    Last updated -
    1
    • Apple
  • -
    security
    F
    license
    -
    quality
    Provides powerful JSON manipulation tools through Model Context Protocol, enabling complex queries, schema generation, and validation with jq notation and native Node.js operations.
    Last updated -
    4
    • Apple
    • Linux
  • A
    security
    A
    license
    A
    quality
    Provides JSON schema generation and filtering tools for LLMs, helping with large JSON files by converting them to TypeScript definitions and extracting specific fields to reduce context size.
    Last updated -
    3
    15
    10
    MIT License

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/EienWolf/jsonshema_mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server