{"id":51702350,"url":"https://github.com/reaatech/structured-output-repair","last_synced_at":"2026-07-16T12:30:50.979Z","repository":{"id":354477729,"uuid":"1221947646","full_name":"reaatech/structured-output-repair","owner":"reaatech","description":"Catch and fix malformed LLM structured outputs instead of crashing. Strip fences, fix JSON syntax, coerce types, re-prompt if unrepairable. Zod schema in, reliable parsed output out.","archived":false,"fork":false,"pushed_at":"2026-06-04T02:50:37.000Z","size":245,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T03:11:58.921Z","etag":null,"topics":["agentic-ai","ai","ai-agents","anthropic","developer-tools","json","llm","openai","typescript"],"latest_commit_sha":null,"homepage":"https://reaatech.com/products/reliability-ops/structured-output-repair","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reaatech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-26T22:05:19.000Z","updated_at":"2026-06-04T02:08:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/reaatech/structured-output-repair","commit_stats":null,"previous_names":["reaatech/structured-output-repair"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/reaatech/structured-output-repair","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reaatech%2Fstructured-output-repair","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reaatech%2Fstructured-output-repair/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reaatech%2Fstructured-output-repair/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reaatech%2Fstructured-output-repair/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reaatech","download_url":"https://codeload.github.com/reaatech/structured-output-repair/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reaatech%2Fstructured-output-repair/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35544514,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai","ai-agents","anthropic","developer-tools","json","llm","openai","typescript"],"created_at":"2026-07-16T12:30:50.502Z","updated_at":"2026-07-16T12:30:50.972Z","avatar_url":"https://github.com/reaatech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# structured-output-repair\n\n[![CI](https://github.com/reaatech/structured-output-repair/actions/workflows/ci.yml/badge.svg)](https://github.com/reaatech/structured-output-repair/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](https://www.typescriptlang.org/)\n\n\u003e Repair malformed LLM structured outputs instead of crashing.\n\nEvery production agent system has this problem: you ask for JSON, you get JSON wrapped in markdown fences, or buried in prose, or with trailing commas, or cut off mid-stream, or with hallucinated/misnamed fields. This library takes a **Zod schema** plus the raw LLM output and attempts graduated repair across six strategies — it either returns valid, schema-conforming data or gives you detailed diagnostics (including best-effort partial data and per-field errors) explaining what went wrong.\n\nThis monorepo provides a core repair engine library and an MCP server tool for use with Claude Desktop and other MCP-compatible clients.\n\n## Features\n\n- **Six graduated repair strategies** — strip-fences, extract-json, fix-json-syntax, coerce-types, fuzzy-match-keys, remove-extra-fields\n- **Prose extraction** — pulls the JSON out of conversational wrappers like `Sure! Here is the JSON: {...}`\n- **Truncation repair** — closes unterminated strings, dangling separators, and missing braces from cut-off streams\n- **Python-literal tolerance** — normalizes `True`/`False`/`None` (and `NaN`/`Infinity`/`undefined`) to valid JSON\n- **Fuzzy key matching** — maps hallucinated/misnamed keys to schema keys (`e-mail` → `email`, `first_name` → `firstName`)\n- **Full type inference** — repaired data inherits the exact `z.infer\u003cT\u003e` type from your Zod schema\n- **Detailed failure diagnostics** — per-strategy step tracking, accumulated errors, best-effort `partialData`, and per-`fieldErrors` paths\n- **Input analysis** — inspect raw LLM output for common issues without applying repairs\n- **MCP server** — expose repair functionality as MCP tools (`structured.repair`, `structured.analyze`) for Claude Desktop and other clients\n- **Rich JSON Schema → Zod conversion** — `anyOf`/`oneOf`/`allOf`, `$ref`/`$defs` (incl. recursive), `const`, `default`, nullable type arrays, `format` (email/uri/uuid/date-time), `additionalProperties`, and tuples\n- **Strategy customization** — pick which strategies to run, in what order\n- **Dual ESM/CJS output** — works with `import` and `require`\n\n## Installation\n\n### Using the packages\n\nPackages are published under the `@reaatech` scope and can be installed individually:\n\n```bash\n# Core repair engine\npnpm add @reaatech/structured-repair-core\n\n# MCP server tool\npnpm add @reaatech/structured-repair-mcp\n```\n\n### Contributing\n\n```bash\n# Clone the repository\ngit clone https://github.com/reaatech/structured-output-repair.git\ncd structured-output-repair\n\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run the test suite\npnpm test\n\n# Run linting\npnpm lint\n```\n\n## Quick Start\n\nRepair LLM output with a single function call:\n\n```typescript\nimport { z } from \"zod\";\nimport { repair } from \"@reaatech/structured-repair-core\";\n\nconst userSchema = z.object({\n  name: z.string(),\n  age: z.number(),\n  email: z.string().email().optional(),\n});\n\n// LLM output with multiple issues — fences, trailing comma, string coercion\nconst llmOutput = '```json\\n{ \"name\": \"John\", \"age\": \"30\" }\\n```';\n\nconst result = await repair(userSchema, llmOutput);\n// =\u003e { name: \"John\", age: 30 }\n```\n\nUse the MCP server with Claude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"structured-repair\": {\n      \"command\": \"npx\",\n      \"args\": [\"@reaatech/structured-repair-mcp\"]\n    }\n  }\n}\n```\n\n## Packages\n\n| Package | Description |\n| ------- | ----------- |\n| [`@reaatech/structured-repair-core`](./packages/core) | Core repair engine with six graduated strategies, types, and error classes |\n| [`@reaatech/structured-repair-mcp`](./packages/mcp) | MCP server exposing repair as tools for Claude Desktop and other MCP clients |\n\n## Repair Strategies\n\nStrategies run in order; the engine validates after each and returns as soon as the data conforms.\n\n| Strategy | What it fixes |\n|----------|---------------|\n| `strip-fences` | Markdown code fences (` ```json {...} ``` `), nested fences, language hints |\n| `extract-json` | JSON embedded in conversational prose (`Here is the JSON: {...}`); string-aware, also recovers truncated tails |\n| `fix-json-syntax` | Trailing commas, missing/unbalanced braces \u0026 brackets, unquoted keys, single quotes, missing commas, comments, `NaN`/`Infinity`/`undefined`, Python `True`/`False`/`None`, and truncated/cut-off output |\n| `coerce-types` | String→number, string→boolean, string→bigint, string→date, nested object/array coercion |\n| `fuzzy-match-keys` | Hallucinated/misnamed keys remapped to schema keys by case/separator (`e-mail` → `email`, `first_name` → `firstName`) |\n| `remove-extra-fields` | Hallucinated fields not in schema, deeply nested (works with `.strict()` schemas) |\n\nOn failure, `repairOutput` returns `partialData` (the best-effort parsed value) and `fieldErrors` (per-field schema violations with dot/bracket paths like `address.zip` or `tags[1]`) alongside the step-by-step `steps` and `errors`.\n\n## Documentation\n\n- [`AGENTS.md`](./AGENTS.md) — AI agent development guide, coding conventions, and monorepo structure\n- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — Contribution workflow, coding standards, and release process\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freaatech%2Fstructured-output-repair","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freaatech%2Fstructured-output-repair","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freaatech%2Fstructured-output-repair/lists"}