json-validate

MCP server for validating JSON against JSON Schema and repairing malformed/invalid JSON.

Features

• validate_json: Validate a JSON instance against a JSON Schema (draft-07 supported)
• explain_validation: Get human-readable explanations and fix suggestions for validation errors
• repair_json: Attempt to repair invalid JSON to match a schema (conservative approach)

Installation

npm install
npm run build

Usage

STDIO Transport (Default)

npm start
# or
node dist/index.js

HTTP Transport

npm start -- --transport http --port 3000
# or
TRANSPORT=http PORT=3000 node dist/index.js

Claude Desktop Configuration

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "json-validate": {
      "command": "node",
      "args": ["/path/to/json-validate/dist/index.js"]
    }
  }
}

Tools

validate_json

Validate a JSON instance against a JSON Schema.

Input:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "age": { "type": "integer", "minimum": 0 }
    },
    "required": ["name"]
  },
  "instance": {
    "name": "John",
    "age": 30
  }
}

Output (Success):

{
  "ok": true,
  "data": {
    "valid": true,
    "errors": []
  },
  "meta": {
    "source": "json-validate",
    "retrieved_at": "2024-01-15T10:30:00.000Z",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

Output (Validation Errors):

{
  "ok": true,
  "data": {
    "valid": false,
    "errors": [
      {
        "path": "/age",
        "keyword": "minimum",
        "message": "must be >= 0",
        "params": { "limit": 0 },
        "schemaPath": "#/properties/age/minimum"
      }
    ]
  },
  "meta": {
    "source": "json-validate",
    "retrieved_at": "2024-01-15T10:30:00.000Z",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

explain_validation

Get human-readable explanations for validation errors.

Input:

{
  "errors": [
    {
      "path": "",
      "keyword": "required",
      "message": "must have required property 'name'",
      "params": { "missingProperty": "name" },
      "schemaPath": "#/required"
    }
  ]
}

Output:

{
  "ok": true,
  "data": {
    "explanations": [
      {
        "path": "",
        "error": "must have required property 'name'",
        "explanation": "The required property \"name\" is missing at root.",
        "suggestion": "Add the missing property \"name\" with an appropriate value."
      }
    ]
  },
  "meta": {
    "source": "json-validate",
    "retrieved_at": "2024-01-15T10:30:00.000Z",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

repair_json

Attempt to repair invalid JSON to match a schema.

Features:

• Parse malformed JSON (trailing commas, single quotes, unquoted keys)
• Apply schema defaults
• Remove additional properties when additionalProperties: false
• Coerce types when safe (e.g., "123" to 123 for number schema)
• Conservative: never invents unknown fields unless schema requires defaults

Input:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "age": { "type": "integer" },
      "active": { "type": "boolean", "default": true }
    },
    "additionalProperties": false
  },
  "instance_or_text": "{'name': 'John', 'age': '30', 'extra': 'field',}"
}

Output:

{
  "ok": true,
  "data": {
    "repaired": {
      "name": "John",
      "age": 30,
      "active": true
    },
    "changes": [
      {
        "path": "/extra",
        "action": "removed",
        "from": "field",
        "reason": "Property not allowed by schema (additionalProperties: false)"
      },
      {
        "path": "/age",
        "action": "coerced",
        "from": "30",
        "to": 30,
        "reason": "Coerced string to integer"
      },
      {
        "path": "/active",
        "action": "defaulted",
        "to": true,
        "reason": "Applied schema default value"
      }
    ],
    "parseErrors": [
      "Standard JSON parse failed, attempting repairs...",
      "JSON repaired successfully with syntax fixes"
    ]
  },
  "meta": {
    "source": "json-validate",
    "retrieved_at": "2024-01-15T10:30:00.000Z",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

CLI Options

Usage: json-validate [options]

Options:
  -t, --transport <type>  Transport type: 'stdio' or 'http' (default: stdio)
  -p, --port <number>     HTTP server port (default: 3000)
  -H, --host <address>    HTTP server host (default: 127.0.0.1)
  -l, --log-level <level> Log level: 'debug', 'info', 'warn', 'error' (default: info)
  -h, --help              Show this help message

Environment Variables

Variable	Description	Default
TRANSPORT	Transport type: stdio or http	stdio
PORT	HTTP server port	3000
HOST	HTTP server host	127.0.0.1
LOG_LEVEL	Log level: debug, info, warn, error	info

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type check
npm run typecheck

# Build
npm run build

Response Envelope

All tools return responses in a standard envelope format:

Success:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "source": "json-validate",
    "retrieved_at": "ISO-8601 timestamp",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

Error:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT | PARSE_ERROR | INTERNAL_ERROR",
    "message": "Human readable message",
    "details": { ... }
  },
  "meta": {
    "retrieved_at": "ISO-8601 timestamp"
  }
}

License

MIT