Jsonschema Validator Mcp

JSON Schema Validator MCP Server

JSON Schema Draft 2020-12、外部参照、リアルタイムのストリーミング検証に対応した、Model Context Protocol（MCP）を実装する包括的な JSON Schema 検証サーバーです。

🚀 特長

• JSON Schema Draft 2020-12 のサポート：最新の JSON Schema 仕様に完全準拠
• 外部参照の解決：HTTP/HTTPS、データベース、ローカルファイル経由で外部スキーマ参照を自動解決
• デュアルサーバーアーキテクチャ：
  • AI アシスタントとの stdio 通信を行う MCP サーバー
  • リアルタイムストリーミングに対応した Web クライアント向け SSE サーバー
• スキーマ管理：スキーマコレクションの完全な CRUD 操作
• 柔軟なデータ保存：PostgreSQL データベースとローカルファイルへのフォールバック
• スキーマ生成：サンプル JSON データから JSON Schema を自動生成
• Docker サポート：コンテナ化されたデプロイに対応

🏗️ アーキテクチャ

コアコンポーネント

• MCP サーバー（mcp_server.py）：AI アシスタント連携用のプライマリサーバー
• SSE サーバー（sse_server.py）：Web クライアント向けの Server-Sent Events 対応 HTTP サーバー
• 検証エンジン（tools/JSONSchemaValidator.py）：JSON Schema Draft 2020-12 バリデーター
• データマネージャー（utils/DataManager.py）：フォールバック戦略による複数ソースのデータ解決
• スキーマジェネレーター（utils/SchemaGenerator.py）：JSON データからスキーマを自動生成

データ解決戦略

1. PostgreSQL データベース（schemas/data_storage テーブル）
2. ローカルファイル（最終フォールバック）

📦 インストール

前提条件

• Python 3.8+
• PostgreSQL（任意、データベース保存用）

クイックスタート

1. リポジトリをクローン

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

2. 依存関係をインストール

   pip install -r requirements.txt
   

3. MCP サーバーを実行

   python mcp_server.py
   

4. SSE サーバーを実行（任意）

   python sse_server.py
   

🔧 設定

環境変数

.env ファイルを作成します：

# 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!

🛠️ 利用可能な MCP ツール

検証ツール

• validate_json_schema：指定したスキーマを使った直接検証
• validate_json_from_collections：保存済みスキーマを使った検証
• get_validation_info：バリデーターの機能と情報

スキーマ管理ツール

• add_update_schema：コレクション内のスキーマを追加または更新
• delete_schema：コレクションからスキーマを削除
• get_schema：スキーマの内容を取得
• list_schemas：利用可能なすべてのスキーマを一覧表示
• generate_schema：JSON データからスキーマを生成

🐳 Docker によるデプロイ

ビルドと実行

# 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 の特長

• マルチステージビルドの最適化
• 非 root ユーザーによるセキュリティ
• ヘルスチェックによる監視
• データ永続化のためのボリュームサポート
• 依存関係の自動管理

🤖 MCP サーバーの設定

Claude Desktop との連携

方法 1：Python を直接実行

Claude Desktop の設定ファイルに追加します：

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 の例：

{
  "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"
      }
    }
  }
}

方法 2：Docker コンテナ

{
  "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 との連携

方法 1：Python を直接実行

MCP 設定ファイルを作成または更新します：

ファイル：~/.mcp/config.json（Linux/macOS）または %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 の例：

{
  "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"
      }
    }
  }
}

方法 2：Docker コンテナ

{
  "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"
      ]
    }
  }
}

設定に関する注意事項

1. データベースの設定：

   • 環境変数は任意です
   • データベースを利用できない場合、サーバーは自動的にローカルのファイルストレージに切り替わります
   • ファイルのみのモードでは、すべての POSTGRES_* 環境変数を省略してください

2. パスの要件：

   • mcp_server.py には絶対パスを使用してください
   • Python がシステムの PATH に含まれていることを確認してください
   • Docker では、イメージがビルドされていることを確認してください：docker build -t jsonschema-mcp-server:1.0.0 .

3. 権限：

   • サーバーに schemas ディレクトリへの書き込み権限があることを確認してください
   • Windows で Docker を使用する場合、ボリュームのマウントを改善するために WSL2 バックエンドを使用してください

4. テストの設定：

   # Test direct execution
   python mcp_server.py
   
   # Test Docker execution  
   docker run -i jsonschema-mcp-server:1.0.0
   

5. ファイルのみの設定（データベースなし）：

   {
     "mcpServers": {
       "jsonschema-validator": {
         "command": "python",
         "args": ["C:\\path\\to\\jsonschema_mcp\\mcp_server.py"]
       }
     }
   }
   

🌐 Web クライアント

このリポジトリには、以下を実演する完全な Web クライアント（client_example.html）が含まれています。

• Server-Sent Events によるリアルタイム検証
• スキーマ管理インターフェース
• 対話型テスト環境
• 進捗の追跡とエラー報告

🔒 セキュリティ機能

• 入力の検証：Linux のパス要件に基づくスキーマ ID 形式の検証
• パスのセキュリティ：ディレクトリトラバーサル攻撃の防止
• 確認の要件：破壊的な操作には明示的な確認が必要です
• エラー処理：機密情報を漏えいさせずに詳細なエラーメッセージを表示します
• 非 root での実行：Docker コンテナは非特権ユーザーとして実行されます

📋 要件

• jsonschema>=4.25.0 - JSON Schema の検証
• mcp>=1.0.0 - Model Context Protocol
• psycopg2-binary>=2.9.0 - PostgreSQL アダプター
• fastapi>=0.104.0 - SSE サーバーフレームワーク
• uvicorn>=0.24.0 - ASGI サーバー
• pydantic>=2.5.0 - データ検証
• ruff>=0.8.0 - コードのリントとフォーマット

🆘 トラブルシューティング

よくある問題

1. データベースへの接続に失敗する

   • PostgreSQL が実行中であることを確認してください
   • .env 内の認証情報を確認してください
   • サーバーは自動的にファイルストレージに切り替わります

2. アクセスが拒否される

   • .schemas ディレクトリへの書き込み権限があることを確認してください
   • Docker のボリュームマウントを確認してください

3. スキーマが見つからない

   • スキーマ ID の形式を確認してください（.json で終わる必要があります）
   • list_schemas ツールでスキーマが存在することを確認してください

🗺️ ロードマップ

計画中の機能や今後の開発方針については、ROADMAP.md をご覧ください。DXT パッケージの統合、スキーマ生成機能の強化、AI を活用した機能などを予定しています。

📄 ライセンス

このプロジェクトは、カスタム非営利ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• Model Context Protocol（MCP）の仕様に基づいて構築されています
• 検証には jsonschema ライブラリを使用しています
• 最新の API 設計パターンに着想を得ています
• AI アシスタントとの統合を想定して設計されています

📞 サポート

問題、質問、貢献については、以下をご確認ください。

1. 上記のトラブルシューティングのセクションを確認する
2. 既存の問題とドキュメントを確認する
3. 以下の情報を含む詳細な問題報告を作成する：
   • エラーメッセージ
   • 再現手順
   • 環境の詳細
   • 期待される動作と実際の動作

---

AI と開発者のコミュニティのために ❤️ を込めて