Jsonschema Validator Mcp

JSON Schema 验证器 MCP 服务

一个功能全面的 JSON Schema 验证服务，基于 Model Context Protocol（MCP）实现，支持 JSON Schema Draft 2020-12、外部引用和实时流式验证。

🚀 功能

• 支持 JSON Schema Draft 2020-12：完全符合最新的 JSON Schema 规范
• 外部引用解析：通过 HTTP/HTTPS、数据库或本地文件自动解析外部 Schema 引用
• 双服务架构：
  • 用于与 AI 助手通过 stdio 通信的 MCP 服务
  • 面向 Web 客户端并支持实时流式传输的 SSE 服务
• Schema 管理：对 Schema 集合执行完整的 CRUD 操作
• 灵活的数据存储：PostgreSQL 数据库，并支持回退到本地文件
• Schema 生成：根据 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）：支持回退策略的多来源数据解析
• Schema 生成器（utils/SchemaGenerator.py）：根据 JSON 数据自动生成 Schema

数据解析策略

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：使用提供的 Schema 直接进行验证
• validate_json_from_collections：使用已存储的 Schema 进行验证
• get_validation_info：查看验证器的功能和信息

Schema 管理工具

• add_update_schema：在集合中添加或更新 Schema
• delete_schema：从集合中删除 Schema
• get_schema：获取 Schema 内容
• list_schemas：列出所有可用的 Schema
• generate_schema：根据 JSON 数据生成 Schema

🐳 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 和开发者社区倾心打造 ❤️