# 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**
   ```bash
   git clone https://github.com/EienWolf/jsonshema_mcp.git
   cd jsonschema_mcp
   ```

2. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the MCP server**
   ```bash
   python mcp_server.py
   ```

4. **Run the SSE server (optional)**
   ```bash
   python sse_server.py
   ```


## 🔧 Configuration

### Environment Variables

Create a `.env` file:

```bash
# 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

```bash
# 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`

```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:**
```json
{
  "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

```json
{
  "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)

```json
{
  "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:**
```json
{
  "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

```json
{
  "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**:
   ```bash
   # 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):
   ```json
   {
     "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](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](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**