json-validate

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: ``json { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer", "minimum": 0 } }, "required": ["name"] }, "instance": { "name": "John", "age": 30 } } ``

Output (Success): ``json { "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): ``json { "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: ``json { "errors": [ { "path": "", "keyword": "required", "message": "must have required property 'name'", "params": { "missingProperty": "name" }, "schemaPath": "#/required" } ] } ``

Output: ``json { "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: ``json { "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: ``json { "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: ``json { "ok": true, "data": { ... }, "meta": { "source": "json-validate", "retrieved_at": "ISO-8601 timestamp", "pagination": { "next_cursor": null }, "warnings": [] } } ``

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

License

MIT