69 lines
1.5 KiB
Markdown
69 lines
1.5 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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.
|