Skip to main content

:::warning AUTO-GENERATED — do not edit This page is generated from the MCP server snapshot content/backend-mcp.json. Edit the source MCP server (not this file), then run npm run generate. :::

Add standard limit/offset pagination + response envelope

When to use: A read route can return many rows and should be paginated.

Prerequisites​

  • The read route exists and wires the DB (see wire-db-read).

Steps​

Step 1: Fetch the DB access pattern to align pagination with the query shape.​

Tools: get_db_pattern

Step 2: Parse and clamp limit and offset query params with safe defaults and a maximum limit.​

Step 3: Apply LIMIT/OFFSET to the parameterized SELECT and also compute the total count.​

Step 4: Return the standard paginated envelope: { data, limit, offset, total }.​

Step 5: Run the verify gate.​

Tools: validate_backend_endpoint

Full recipe definition​

The complete machine-readable recipe as returned by the MCP server:

{
  "id": "add-pagination",
  "title": "Add standard limit/offset pagination + response envelope",
  "when": "A read route can return many rows and should be paginated.",
  "prerequisites": [
    "The read route exists and wires the DB (see wire-db-read)."
  ],
  "steps": [
    {
      "action": "Fetch the DB access pattern to align pagination with the query shape.",
      "tools": [
        "get_db_pattern"
      ],
      "note": "Apply LIMIT/OFFSET at the SQL level, not by slicing a fully-materialized result in Python."
    },
    {
      "action": "Parse and clamp `limit` and `offset` query params with safe defaults and a maximum limit.",
      "files": [
        "src/routes/<domain>_routes.py"
      ],
      "note": "Reject non-integer/negative values with 400. Cap limit to a sane maximum to protect the DB."
    },
    {
      "action": "Apply LIMIT/OFFSET to the parameterized SELECT and also compute the total count.",
      "files": [
        "src/routes/<domain>_routes.py"
      ],
      "note": "Keep params bound — never interpolate limit/offset into the SQL string."
    },
    {
      "action": "Return the standard paginated envelope: { data, limit, offset, total }.",
      "files": [
        "src/routes/<domain>_routes.py"
      ]
    },
    {
      "action": "Run the verify gate.",
      "tools": [
        "validate_backend_endpoint"
      ],
      "note": "Follow run-verify."
    }
  ],
  "filesToCreate": [],
  "validation": [
    "limit/offset are validated, clamped, and applied in SQL.",
    "Response includes data + limit + offset + total.",
    "Invalid pagination params return 400."
  ],
  "doneCriteria": [
    "Route paginates via LIMIT/OFFSET and returns the standard envelope with a total count.",
    "run-verify passes."
  ],
  "commonMistakes": [
    "Fetching all rows then slicing in Python instead of using SQL LIMIT/OFFSET.",
    "No maximum cap on limit (lets a caller request the whole table).",
    "Interpolating limit/offset into the SQL string.",
    "Omitting total, so the client can't build pagination controls."
  ],
  "relatedRecipes": [
    "wire-db-read",
    "create-endpoint",
    "run-verify"
  ]
}