@reaatech/structured-repair-mcp

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

MCP (Model Context Protocol) server that exposes structured-output-repair as tools. Use with Claude Desktop, Cursor, or any MCP-compatible client to repair malformed LLM structured outputs via structured tool calls.

Installation

npm install @reaatech/structured-repair-mcp
# or
pnpm add @reaatech/structured-repair-mcp

Feature Overview

• Two MCP tools — structured.repair and structured.analyze
• JSON Schema input — describe your expected output shape as standard JSON Schema (no programmatic Zod required)
• Automatic schema conversion — JSON Schema → Zod is handled internally
• Strategy control — choose which repair strategies to apply per tool call
• Input analysis — inspect LLM output for common issues before committing to repair
• Stdio transport — standard MCP transport, compatible with all MCP clients
• Dual ESM/CJS output — works with import and require

Quick Start

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "structured-repair": {
      "command": "npx",
      "args": ["@reaatech/structured-repair-mcp"]
    }
  }
}

Using the MCP Server Programmatically

import { createStructuredRepairServer } from "@reaatech/structured-repair-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
const server = createStructuredRepairServer();
 
// Listen on stdio
const transport = new StdioServerTransport();
await server.connect(transport);

Tools

structured.repair

Repair malformed LLM output against a JSON Schema. Accepts a raw string input, a schema object (JSON Schema), and optional options.

{
  "name": "structured.repair",
  "arguments": {
    "input": "```json\n{\"name\": \"Alice\", \"age\": \"30\"}\n```",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "age": { "type": "number" }
      },
      "required": ["name", "age"]
    },
    "options": {
      "debug": false,
      "strategies": ["strip-fences", "fix-json-syntax", "coerce-types"]
    }
  }
}

Response:

{
  "success": true,
  "data": { "name": "Alice", "age": 30 },
  "originalInput": "```json\n{\"name\": \"Alice\", \"age\": \"30\"}\n```",
  "repairedInput": "{\"name\": \"Alice\", \"age\": \"30\"}",
  "steps": [
    { "strategy": "strip-fences", "success": true },
    { "strategy": "fix-json-syntax", "success": true },
    { "strategy": "coerce-types", "success": true }
  ],
  "errors": []
}

structured.repair Arguments

structured.analyze

Analyze raw input for repair issues without applying repairs. Useful for diagnostics or conditional tool flows.

{
  "name": "structured.analyze",
  "arguments": {
    "input": "```json\n{\"a\": 1, }\n```"
  }
}

Response:

{
  "isValidJson": false,
  "hasFences": true,
  "issues": [
    { "type": "fence-wrapper", "description": "Input is wrapped in markdown code fences" },
    { "type": "trailing-comma", "description": "Trailing comma found before closing brace" }
  ]
}

structured.analyze Arguments

Supported JSON Schema Subset

The MCP server converts JSON Schema to Zod internally. Currently supported keywords:

Not yet supported: $ref, $defs, allOf, anyOf, oneOf, additionalProperties, format.

Security Note: pattern is compiled with new RegExp(...). Only pass schemas from trusted sources — a pathological pattern can cause catastrophic backtracking (ReDoS) in the server process.

API Reference

createStructuredRepairServer(): Server

Creates and configures an MCP server instance with structured.repair and structured.analyze tools registered.

import { createStructuredRepairServer } from "@reaatech/structured-repair-mcp";
 
const server = createStructuredRepairServer();
// Server has two tools: structured.repair, structured.analyze

startServer(): Promise<void>

Creates a server, connects it to StdioServerTransport, and begins listening. This is the entry point called by the binary (npx @reaatech/structured-repair-mcp).

import { startServer } from "@reaatech/structured-repair-mcp";
 
await startServer();

jsonSchemaToZod(schema: Record<string, unknown>): z.ZodType

Converts a JSON Schema object to a Zod schema. Used internally but exported for direct use.

import { jsonSchemaToZod } from "@reaatech/structured-repair-mcp";
 
const zodSchema = jsonSchemaToZod({
  type: "object",
  properties: {
    name: { type: "string", minLength: 1 },
    age: { type: "number", minimum: 0 },
  },
  required: ["name"],
});
 
// zodSchema is a Zod schema ready for validation

Related Packages

• @reaatech/structured-repair-core — Core repair engine with four graduated strategies

License

MIT