| name | mas-api-contract |
| description | Define backend API contract standards for FastAPI services. Use when adding or refactoring HTTP/WebSocket endpoints in app/api, designing request/response schemas in app/models/schema.py, standardizing status/error contracts, and maintaining backward compatibility for clients. |
MAS API Contract
Objective
Keep backend API interfaces stable, consistent, and easy to consume.
Global Constraints
Apply these constraints while using this skill.
- Make minimal necessary changes first; avoid broad refactors unless explicitly requested.
- Align with current code style and existing project conventions in the touched module.
- Avoid over-engineering, over-abstraction, and defensive programming that does not match existing code patterns.
- Study similar existing implementations deeply before coding and follow established local patterns.
Scope
Apply to:
- HTTP endpoints under
app/api/*.
- Request/response schema models in
app/models/schema.py.
- WebSocket message contracts used by backend services.
Current dev baseline:
- Keep FastAPI responses aligned with
OutBase-style envelopes used in app/models/schema.py.
- Keep WebSocket contracts aligned with current envelope conventions already used by
app/api/core.py and WS command routes.
MCP Surface
The backend exposes an MCP server derived from the live OpenAPI schema. Know these facts before changing API surface:
main.py mounts it with fastapi_mcp.FastApiMCP(...).mount_http(), so the transport is streamable HTTP at /mcp. It is not an SSE endpoint; do not describe or document it as one.
