agent-json-reliability

Agent JSON Reliability

STATUS=BETA version 0.1.0

AI agents and software frequently emit malformed JSON: markdown fences, trailing commas, single quotes, True/False/None, and extra prose around one object.

Agent JSON Reliability is a deterministic pipeline for that failure mode:

• inspect — diagnose whether the text is JSON and which failures are present
• safe repair — apply only structural, unambiguous fixes
• validate — optional JSON Schema check on the result
• structured diagnostics — valid_original, repaired, valid_final, schema_valid, unsafe_or_ambiguous, changes, errors

This is not a generic jsonschema wrapper. The primary value is turning malformed agent output into reliable structured data without an LLM and without inventing semantic values.

When repair would require guessing (truncated objects, missing values, competing JSON documents), the service refuses. That is correct behavior.

Primary HTTP endpoint: POST /v1/json/reliable

MCP tools (same core functions, no duplicate implementation): json_reliable / reliable_json, validate_json, repair_json, inspect_json

Before / after (safe repair)

Malformed agent output:

{
  "text": "```json\n{\"name\":\"alice\",\"age\":30,}\n```"
}

Expected result (semantically equivalent valid JSON):

• valid_original=false
• repaired=true
• valid_final=true
• unsafe_or_ambiguous=false
• json → {"name":"alice","age":30}

If a schema is supplied and satisfied: schema_valid=true.

Safe refusal (ambiguous)

Truncated input such as {"user": is JSON-intended but not deterministically repairable without inventing keys or values.

Expected:

• HTTP 200 (documented safe response)
• valid_final=false
• unsafe_or_ambiguous=true or repaired=false

Do not treat a correct refusal as a product failure.

Run locally (no Hunter)

python -m pip install -r requirements.txt
python serve.py

Binds 127.0.0.1:8770 by default. Set PUBLIC_BASE_URL to an HTTPS origin only when you expose the process yourself. Do not commit a temporary tunnel hostname as the canonical URL.

HTTP examples

See examples/curl.md, examples/python.py, examples/javascript.js.

Remote examples use ${PUBLIC_BASE_URL}. Local default is http://127.0.0.1:8770.

Share URLs (optional, unverified telemetry tags):

• /?source=github
• /?source=mcp-registry
• /?source=api-directory

MCP (stdio — durable)

Package transport does not depend on a temporary public URL.

{
  "mcpServers": {
    "agent-json-reliability": {
      "command": "python",
      "args": ["-m", "products.gateway.mcp_stdio"]
    }
  }
}

After you publish to PyPI (free): uvx agent-json-reliability.

Remote HTTP MCP (POST /mcp) is for a running instance. Prefer stdio/package for Official MCP Registry metadata.

Machine discovery

• GET /.well-known/agent-services.json
• GET /openapi.json
• GET /llms.txt
• GET /AGENTS.md
• POST /mcp JSON-RPC (tools/list, tools/call)

What this package does not include

No Hunter market database, no private reports, no Windows user paths, no collectors, no wallets, no x402 payment.

Free beta: no auth, no payment.