schemeta/docs/api-mcp-contracts.md

API + MCP Contract Policy

This document defines compatibility expectations for Schemeta API and MCP tools.

Version Fields

All successful API/MCP structured responses include:

• api_version
• schema_version

HTTP API responses also include:

• request_id (response field + x-request-id header)

Compatibility Policy

• Additive changes are allowed within the same api_version minor release.
• Breaking shape changes require a new API major version.
• schema_version increments when SJM schema semantics or required fields change.

HTTP API Contracts

Stable endpoints:

• POST /compile
• POST /analyze
• POST /layout/auto
• POST /layout/tidy
• GET /health
• GET /mcp/ui-bundle

Error envelope shape:

{
  "ok": false,
  "request_id": "uuid-or-forwarded-id",
  "error": {
    "code": "stable_machine_code",
    "message": "human-readable description"
  }
}

MCP Tool Contracts

Stable tool names:

• schemeta_compile
• schemeta_analyze
• schemeta_ui_bundle

Contract rules:

• Tool names are stable across minor versions.
• Input schemas may gain optional fields additively.
• Structured response fields are additive-only within a minor.

Persistence and Restore

UI workspace persistence is expected to support:

• deterministic JSON export/import roundtrip
• local snapshot restore path (schemeta:snapshots:v2)
• reset-to-sample baseline recovery for QA loops

These are validated in release checklist + browser regression flow.