JSON模式验证器MCP服务器
一个全面的JSON模式验证服务器，实现了模型上下文协议（MCP），支持JSON模式草案2020-12、外部引用和实时流验证。
🚀 特性
- JSON模式草案2020-12支持：完全符合最新的JSON模式规范
- 外部参考分辨率：通过HTTP/HTTPS、数据库或本地文件自动解析外部架构引用
- 双服务器架构:
- 用于与AI助手进行stdio通信的MCP服务器 - 用于实时流媒体web客户端的SSE服务器
- 模式管理：完成模式集合的CRUD操作
- 数据存储灵活性：带本地文件回退的PostgreSQL数据库
- 模式生成：从示例JSON数据自动生成JSON模式
- Docker支持：容器化部署就绪
🏗️ 建筑
核心组件
- MCP服务器 (
mcp_server.py)：用于AI助手集成的主服务器 - SSE服务器 (
sse_server.py)：带有web客户端服务器发送事件的HTTP服务器 - 验证引擎 (
tools/JSONSchemaValidator.py)：2020-12年JSON模式草案验证器 - 数据管理器 (
utils/DataManager.py)：具有回退策略的多源数据解析 - 模式生成器 (
utils/SchemaGenerator.py)：从JSON数据自动生成模式
数据解析策略
- PostgreSQL数据库 （模式/数据存储表）
- 本地文件 （最终回退）
📦 安装
先决条件
- Python 3.8+
- PostgreSQL（可选，用于数据库存储）
快速开始
- 克隆存储库
git clone https://github.com/EienWolf/jsonshema_mcp.git
cd jsonschema_mcp- 安装依赖项
pip install -r requirements.txt- 运行MCP服务器
python mcp_server.py- 运行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.0Docker功能
- 多阶段构建优化
- 非root用户安全
- 健康检查监测
- 数据持久性的批量支持
- 自动依赖关系管理
🤖 MCP服务器配置
Claude桌面集成
方法1：直接执行Python
添加到您的Claude Desktop配置文件中：
视窗: %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复制集成
方法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"
]
}
}
}配置说明
- 数据库配置:
- 环境变量是可选的 - 如果数据库不可用，服务器会自动回退到本地文件存储 - 对于仅文件模式，省略所有 POSTGRES_* 环境变量
- 路径要求:
- 使用绝对路径 mcp_server.py - 确保Python在您的系统PATH中 - 对于Docker，确保镜像已构建： docker build -t jsonschema-mcp-server:1.0.0 .
- 权限:
- 确保服务器具有对架构目录的写入权限 - 对于Windows上的Docker，使用WSL2后端进行更好的卷挂载
- 测试配置:
# Test direct execution
python mcp_server.py
# Test Docker execution
docker run -i jsonschema-mcp-server:1.0.0- 仅文件配置 （无数据库）：
{
"mcpServers": {
"jsonschema-validator": {
"command": "python",
"args": ["C:\\path\\to\\jsonschema_mcp\\mcp_server.py"]
}
}
}🌐 web客户端
该存储库包括一个完整的web客户端(client_example.html)演示：
- 使用服务器发送事件进行实时验证
- 架构管理界面
- 交互式测试环境
- 进度跟踪和错误报告
🔒 安全功能
- 输入验证：根据Linux路径要求进行架构ID格式验证
- 路径安全：防止目录遍历攻击
- 确认要求：明确确认破坏性操作
- 错误处理：详细的错误消息，没有敏感信息泄露
- 非根执行：Docker容器以非特权用户身份运行
📋 需求
jsonschema>=4.25.0-JSON模式验证mcp>=1.0.0-模型上下文协议psycopg2-binary>=2.9.0-PostgreSQL适配器fastapi>=0.104.0-SSE服务器框架uvicorn>=0.24.0-ASGI服务器pydantic>=2.5.0-数据验证ruff>=0.8.0-代码过滤和格式化
🆘 故障排除
常见问题
- 数据库连接失败
- 检查PostgreSQL是否正在运行 - 验证中的凭据 .env - 服务器自动回退到文件存储
- 权限不足
- 确保的写入权限 .schemas 目录 - 检查Docker卷挂载
- 未找到架构
- 验证架构ID格式（必须以结尾 .json) - 检查架构是否存在 list_schemas 工具
🗺️ Roadmap
查看我们的 ROADMAP.md 对于计划中的功能和未来的发展方向，包括DXT包集成、增强的模式生成和AI驱动的功能。
📄 许可证
本项目根据定制非商业许可证获得许可。请参阅 许可证 文件以获取详细信息。
🙏 致谢
- 基于模型上下文协议（MCP）规范构建
- 使用
jsonschema验证库 - 灵感来自现代API设计模式
- 专为与AI助手集成而设计
📞 支持
对于问题、疑问或贡献：
- 检查上面的故障排除部分
- 审查现有问题和文件
- 使用以下内容创建详细的问题报告：
- 错误消息 - 重现步骤 - 环境详细信息 - 预期行为与实际行为
______________________________________________________________________
由以下材料制成❤️ 面向人工智能和开发人员社区