README.md•9.97 kB
# 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**