Mas API Contract

MAS API Contract

Objective

Keep backend API interfaces stable, consistent, and easy to consume.

Global Constraints

Apply these constraints while using this skill.

1. Make minimal necessary changes first; avoid broad refactors unless explicitly requested.
2. Align with current code style and existing project conventions in the touched module.
3. Avoid over-engineering, over-abstraction, and defensive programming that does not match existing code patterns.
4. Study similar existing implementations deeply before coding and follow established local patterns.

Scope

Apply to:

1. HTTP endpoints under app/api/*.
2. Request/response schema models in app/models/schema.py.
3. WebSocket message contracts used by backend services.

Current dev baseline:

1. Keep FastAPI responses aligned with OutBase-style envelopes used in app/models/schema.py.
2. 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:

1. 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.
2. Mounting is gated by AUTO_MAS_ENABLE_MCP (default "1") and happens in background initialization after lifespan yields. The route is absent until that finishes, so an early request can legitimately 404.
3. MCP tools are generated from the full OpenAPI schema with describe_full_response_schema=True and describe_all_responses=True. Every route you add, rename, or retype becomes an MCP tool signature automatically, and schema churn is user-visible through this surface as well as through the generated frontend client.
4. exclude_tags=["Delete"] keeps destructive routes out of MCP. A destructive endpoint must carry tags=["Delete"] to stay excluded; path or method naming alone does not exclude it.
5. Treat /mcp and its tool names as an external contract. Route path, operation_id, and tag changes are breaking for MCP clients even when the HTTP API stays compatible.

Contract Principles

1. Keep one clear contract per endpoint action.
2. Keep request and response types explicit and version-safe.
3. Keep error semantics predictable across endpoints.
4. Keep compatibility-first behavior for public contract changes.

Endpoint Naming Rules

1. Use resource-oriented prefixes: /api/<resource>.
2. Keep action suffixes explicit for non-CRUD operations (/start, /stop, /reorder).
3. Keep endpoint names concise and unambiguous.
4. Avoid introducing equivalent endpoints with different verbs/paths.
5. For POST query-style endpoints such as combobox/list options, prefer one endpoint with an explicit request-body discriminator over splitting equivalent endpoints by implementation type.
6. Do not create parallel paths like /xxx-foo and /xxx-bar solely because the backend reads different config books; keep the path semantic stable and put the selected type in the body.

Request/Response Schema Rules

1. Use *In for request models.
2. Use *Out for response models.
3. Use shared OutBase for common response envelope fields when applicable.
4. Bind endpoint response_model explicitly.
5. Do not return raw untyped dicts if a schema model exists.
6. When a request needs to choose between known plan/script/config families, model that selector explicitly instead of encoding it in the URL path or handler name.
7. Define or update request/response data models in app/models/schema.py before wiring a new route.
8. Create routes in the corresponding app/api/ module and keep route handlers as thin transport adapters around schema models and backend calls.

Field Naming Rules

1. Keep external API fields stable and consistent per established style.
2. Reuse canonical shared semantic names via mas-schema-naming.
3. Avoid introducing synonym fields for the same semantic.
4. Keep ID fields consistent by entity (scriptId, queueId, userId, etc.).