@centia-io/mcp-server 1.0.19 → 1.0.22

package/centia-api.json

@@ -3799,20 +3799,530 @@
                 }
             }
         },
+        "/api/v4/schemas/{schema}/relations/{relation}/snapshots": {
+            "get": {
+                "tags": [
+                    "Snapshots"
+                ],
+                "description": "List the published snapshots of a relation, newest first. Returns a bare array like every other v4 collection.",
+                "operationId": "getRelationSnapshots",
+                "parameters": [
+                    {
+                        "name": "schema",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "relation",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Ok",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/RelationSnapshot"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "Insufficient privileges"
+                    }
+                }
+            }
+        },
+        "/api/v4/schemas/{schema}/relations/{relation}/snapshots/{date}": {
+            "get": {
+                "tags": [
+                    "Snapshots"
+                ],
+                "description": "Get one published snapshot (metadata).",
+                "operationId": "getRelationSnapshot",
+                "parameters": [
+                    {
+                        "name": "schema",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "relation",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "date",
+                        "in": "path",
+                        "description": "Snapshot date YYYY-MM-DD",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "format": "date"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Ok",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/RelationSnapshot"
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "Insufficient privileges"
+                    },
+                    "404": {
+                        "description": "No published snapshot for that date"
+                    }
+                }
+            }
+        },
+        "/api/v4/schemas/{schema}/relations/{relation}/snapshots/{date}/data": {
+            "get": {
+                "tags": [
+                    "Snapshots"
+                ],
+                "description": "The snapshot's Parquet file. Supports HEAD and single byte ranges (206/416). In redirect mode answers 302 to a short-lived storage URL.",
+                "operationId": "getRelationSnapshotData",
+                "parameters": [
+                    {
+                        "name": "schema",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "relation",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "date",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "format": "date"
+                        }
+                    },
+                    {
+                        "name": "Range",
+                        "in": "header",
+                        "required": false,
+                        "schema": {
+                            "type": "string"
+                        },
+                        "example": "bytes=0-1023"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Whole file",
+                        "content": {
+                            "application/vnd.apache.parquet": {}
+                        }
+                    },
+                    "206": {
+                        "description": "Partial content"
+                    },
+                    "302": {
+                        "description": "Redirect to a presigned URL (redirect mode)"
+                    },
+                    "403": {
+                        "description": "Insufficient privileges"
+                    },
+                    "404": {
+                        "description": "No published snapshot for that date"
+                    },
+                    "409": {
+                        "description": "Snapshot has several files; use /files/{file}"
+                    },
+                    "416": {
+                        "description": "Range not satisfiable"
+                    },
+                    "502": {
+                        "description": "Snapshot storage unavailable"
+                    }
+                }
+            }
+        },
+        "/api/v4/schemas/{schema}/relations/{relation}/snapshots/{date}/files/{file}": {
+            "get": {
+                "tags": [
+                    "Snapshots"
+                ],
+                "description": "One file of the snapshot by catalog name (data-<id>.parquet, metadata-<id>.json). Same HEAD/Range semantics as /data.",
+                "operationId": "getRelationSnapshotFile",
+                "parameters": [
+                    {
+                        "name": "schema",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "relation",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "date",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "format": "date"
+                        }
+                    },
+                    {
+                        "name": "file",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "File"
+                    },
+                    "206": {
+                        "description": "Partial content"
+                    },
+                    "403": {
+                        "description": "Insufficient privileges"
+                    },
+                    "404": {
+                        "description": "Unknown snapshot or file"
+                    },
+                    "416": {
+                        "description": "Range not satisfiable"
+                    },
+                    "502": {
+                        "description": "Snapshot storage unavailable"
+                    }
+                }
+            }
+        },
         "/api/v4/interfaces": {
             "get": {
                 "tags": [
-                    "Methods"
+                    "Methods"
+                ],
+                "description": "Get TypeScript interfaces for RPC methods inferred from /api/v4/call/dry.",
+                "operationId": "getTypeScript",
+                "responses": {
+                    "200": {
+                        "description": "Ok",
+                        "content": {
+                            "text/plain": {}
+                        }
+                    }
+                }
+            }
+        },
+        "/api/v4/scheduler/jobs/{id}": {
+            "get": {
+                "tags": [
+                    "Scheduler"
+                ],
+                "description": "Get one or more jobs (comma separated ids), or list all jobs of the database.",
+                "operationId": "getSchedulerJob",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "description": "Job id, or comma separated ids. Omit to list all jobs of the database.",
+                        "required": false,
+                        "schema": {
+                            "type": "string"
+                        },
+                        "example": "5497,5498"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Ok",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "oneOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SchedulerJob"
+                                        },
+                                        {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "#/components/schemas/SchedulerJob"
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found"
+                    }
+                }
+            },
+            "delete": {
+                "tags": [
+                    "Scheduler"
+                ],
+                "description": "Delete one or more jobs (comma separated ids). Refused while a run of any of them is running.",
+                "operationId": "deleteSchedulerJob",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "description": "Job id, or comma separated ids",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        },
+                        "example": "5497,5498"
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "Deleted"
+                    },
+                    "404": {
+                        "description": "Not found"
+                    },
+                    "409": {
+                        "description": "A run is in progress"
+                    }
+                }
+            },
+            "patch": {
+                "tags": [
+                    "Scheduler"
+                ],
+                "description": "Update fields of a job.",
+                "operationId": "patchSchedulerJob",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "integer"
+                        }
+                    }
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/SchedulerJob"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "303": {
+                        "description": "Updated"
+                    },
+                    "400": {
+                        "description": "Bad request"
+                    },
+                    "404": {
+                        "description": "Not found"
+                    }
+                }
+            }
+        },
+        "/api/v4/scheduler/jobs": {
+            "post": {
+                "tags": [
+                    "Scheduler"
+                ],
+                "description": "Create one or more jobs.",
+                "operationId": "postSchedulerJob",
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "oneOf": [
+                                    {
+                                        "$ref": "#/components/schemas/SchedulerJobInput"
+                                    },
+                                    {
+                                        "type": "array",
+                                        "items": {
+                                            "$ref": "#/components/schemas/SchedulerJobInput"
+                                        }
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "201": {
+                        "description": "Created"
+                    },
+                    "400": {
+                        "description": "Bad request"
+                    }
+                }
+            }
+        },
+        "/api/v4/scheduler/runs/{uuid}": {
+            "get": {
+                "tags": [
+                    "Scheduler"
+                ],
+                "description": "Get one run, or list runs (running first, then the newest finished). Filters: ?job=, ?status=.",
+                "operationId": "getSchedulerRun",
+                "parameters": [
+                    {
+                        "name": "uuid",
+                        "in": "path",
+                        "description": "Run uuid. Omit to list runs (running plus the newest finished ones).",
+                        "required": false,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "job",
+                        "in": "query",
+                        "required": false,
+                        "schema": {
+                            "type": "integer"
+                        }
+                    },
+                    {
+                        "name": "status",
+                        "in": "query",
+                        "required": false,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
                 ],
-                "description": "Get TypeScript interfaces for RPC methods inferred from /api/v4/call/dry.",
-                "operationId": "getTypeScript",
                 "responses": {
                     "200": {
                         "description": "Ok",
                         "content": {
-                            "text/plain": {}
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/SchedulerRun"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found"
+                    }
+                }
+            },
+            "delete": {
+                "tags": [
+                    "Scheduler"
+                ],
+                "description": "Stop a running run: SIGINT, then SIGKILL after 30 s.",
+                "operationId": "deleteSchedulerRun",
+                "parameters": [
+                    {
+                        "name": "uuid",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Signal sent"
+                    },
+                    "404": {
+                        "description": "No running run with that uuid"
+                    },
+                    "409": {
+                        "description": "The run is on another host"
+                    }
+                }
+            }
+        },
+        "/api/v4/scheduler/runs": {
+            "post": {
+                "tags": [
+                    "Scheduler"
+                ],
+                "description": "Start a job now. Asynchronous: poll the runs list for the new run.",
+                "operationId": "postSchedulerRun",
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "required": [
+                                    "job"
+                                ],
+                                "properties": {
+                                    "job": {
+                                        "type": "integer"
+                                    },
+                                    "force": {
+                                        "description": "Ignore delete_append and overwrite",
+                                        "type": "boolean"
+                                    }
+                                },
+                                "type": "object"
+                            }
                         }
                     }
+                },
+                "responses": {
+                    "202": {
+                        "description": "Starting"
+                    },
+                    "404": {
+                        "description": "Job not found"
+                    },
+                    "409": {
+                        "description": "A run of the job is already running"
+                    }
                 }
             }
         },
@@ -4265,17 +4775,180 @@
                                 ]
                             }
                         }
-                    }
-                },
-                "responses": {
-                    "201": {
-                        "description": "Created"
+                    }
+                },
+                "responses": {
+                    "201": {
+                        "description": "Created"
+                    },
+                    "400": {
+                        "description": "Bad request"
+                    },
+                    "404": {
+                        "description": "Not found"
+                    }
+                }
+            }
+        },
+        "/api/v4/snapshots/{id}": {
+            "get": {
+                "tags": [
+                    "Snapshots"
+                ],
+                "description": "Get one snapshot job (object), or several by comma separated ids (array).",
+                "operationId": "getSnapshot",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "description": "Snapshot id, or comma separated ids",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Ok",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "oneOf": [
+                                        {
+                                            "$ref": "#/components/schemas/Snapshot"
+                                        },
+                                        {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "#/components/schemas/Snapshot"
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "Super-user only"
+                    },
+                    "404": {
+                        "description": "Not found"
+                    }
+                }
+            }
+        },
+        "/api/v4/snapshots": {
+            "get": {
+                "tags": [
+                    "Snapshots"
+                ],
+                "description": "List the newest snapshot jobs.",
+                "operationId": "getSnapshots",
+                "parameters": [
+                    {
+                        "name": "schema",
+                        "in": "query",
+                        "description": "List filter: schema",
+                        "required": false,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "relation",
+                        "in": "query",
+                        "description": "List filter: relation",
+                        "required": false,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Ok",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/Snapshot"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "Super-user only"
+                    }
+                }
+            },
+            "post": {
+                "tags": [
+                    "Snapshots"
+                ],
+                "description": "Queue a Parquet snapshot of one relation (object) or several (array of objects). Returns 202; poll the returned link(s) for status. With an array, every relation is checked before anything is queued.",
+                "operationId": "postSnapshot",
+                "requestBody": {
+                    "description": "Relation(s) to snapshot.",
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "oneOf": [
+                                    {
+                                        "$ref": "#/components/schemas/SnapshotRequest"
+                                    },
+                                    {
+                                        "type": "array",
+                                        "items": {
+                                            "$ref": "#/components/schemas/SnapshotRequest"
+                                        }
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "202": {
+                        "description": "Accepted; poll _links.self for status. An object for a single request, an array for an array request.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "oneOf": [
+                                        {
+                                            "$ref": "#/components/schemas/SnapshotAccepted"
+                                        },
+                                        {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "#/components/schemas/SnapshotAccepted"
+                                            }
+                                        }
+                                    ]
+                                }
+                            }
+                        }
                     },
                     "400": {
                         "description": "Bad request"
                     },
+                    "403": {
+                        "description": "Super-user only"
+                    },
                     "404": {
-                        "description": "Not found"
+                        "description": "Relation not found"
+                    },
+                    "406": {
+                        "description": "POST with a resource id is not allowed"
+                    },
+                    "409": {
+                        "description": "A snapshot of this relation is already pending or running"
+                    },
+                    "501": {
+                        "description": "Snapshot storage is not configured"
                     }
                 }
             }
@@ -7027,6 +7700,198 @@
                 },
                 "type": "object"
             },
+            "RelationSnapshot": {
+                "description": "A published snapshot of a relation.",
+                "properties": {
+                    "snapshot_date": {
+                        "description": "Read API for published GeoParquet snapshots of a relation: list, metadata,\nand the files themselves with HEAD + byte-range support so Parquet readers\n(DuckDB read_parquet) can fetch footers and row groups selectively.\n\nAuthorization runs before any catalog file name or storage call: super\nusers always, sub-users by schema ownership or layer read privilege, and\nnever a sub-user the geofence filters (a whole-table file cannot honour a\nrow filter). Storage failures answer 502 without naming bucket or key.",
+                        "type": "string",
+                        "format": "date",
+                        "example": "2026-09-16"
+                    },
+                    "snapshot_id": {
+                        "type": "string"
+                    },
+                    "row_count": {
+                        "type": "integer"
+                    },
+                    "size_bytes": {
+                        "type": "integer"
+                    },
+                    "schema_version": {
+                        "type": "string"
+                    },
+                    "files": {
+                        "type": "array",
+                        "items": {
+                            "type": "object"
+                        }
+                    },
+                    "published": {
+                        "type": "string",
+                        "format": "date-time"
+                    }
+                },
+                "type": "object"
+            },
+            "SchedulerJobInput": {
+                "description": "A job to create: name, schema, url and schedule are required.",
+                "required": [
+                    "name",
+                    "schema",
+                    "url",
+                    "schedule"
+                ],
+                "allOf": [
+                    {
+                        "$ref": "#/components/schemas/SchedulerJob"
+                    }
+                ]
+            },
+            "SchedulerJob": {
+                "description": "An import job of the scheduler. On PATCH every field is optional.",
+                "properties": {
+                    "name": {
+                        "description": "v4 scheduler jobs: the import jobs of the caller's database (super-user only).\nA job's five cron columns are exposed as one \"schedule\" string.",
+                        "type": "string",
+                        "example": "bygninger"
+                    },
+                    "schema": {
+                        "type": "string",
+                        "example": "geodanmark"
+                    },
+                    "url": {
+                        "type": "string",
+                        "example": "https://example.com/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=bygning"
+                    },
+                    "schedule": {
+                        "description": "Five-field cron expression: min hour dayofmonth month dayofweek",
+                        "type": "string",
+                        "example": "0 3 * * *"
+                    },
+                    "epsg": {
+                        "type": "integer",
+                        "example": 25832
+                    },
+                    "type": {
+                        "description": "ogr2ogr -nlt or AUTO",
+                        "type": "string",
+                        "example": "AUTO"
+                    },
+                    "encoding": {
+                        "type": "string",
+                        "example": "UTF8"
+                    },
+                    "extra": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "delete_append": {
+                        "type": "boolean",
+                        "example": false
+                    },
+                    "download_schema": {
+                        "type": "boolean",
+                        "example": true
+                    },
+                    "presql": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "postsql": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "active": {
+                        "type": "boolean",
+                        "example": true
+                    },
+                    "snapshot": {
+                        "description": "Queue a Parquet snapshot after each successful import",
+                        "type": "boolean",
+                        "example": false
+                    }
+                },
+                "type": "object"
+            },
+            "SchedulerRun": {
+                "description": "One run of a scheduler job.",
+                "properties": {
+                    "uuid": {
+                        "description": "v4 scheduler runs: start a job now, list and inspect runs (the\nstarted_jobs registry kept by get.php), stop a running run.",
+                        "type": "string"
+                    },
+                    "job": {
+                        "type": "integer"
+                    },
+                    "name": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "pid": {
+                        "type": "integer"
+                    },
+                    "host": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "slot": {
+                        "type": [
+                            "integer",
+                            "null"
+                        ]
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": [
+                            "running",
+                            "succeeded",
+                            "failed",
+                            "skipped",
+                            "lost"
+                        ]
+                    },
+                    "stale": {
+                        "description": "No progress signal (heartbeat or start) for 5 minutes",
+                        "type": "boolean"
+                    },
+                    "started_at": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "heartbeat": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time"
+                    },
+                    "finished_at": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time"
+                    },
+                    "exit_reason": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    }
+                },
+                "type": "object"
+            },
             "Schema": {
                 "description": "Schema definition, including tables and sequences.",
                 "required": [
@@ -7123,6 +7988,171 @@
                 },
                 "type": "object"
             },
+            "SnapshotAccepted": {
+                "description": "A queued snapshot job.",
+                "properties": {
+                    "id": {
+                        "description": "Asynchronous Parquet snapshots of a table or view to S3.\n\nPOST queues a job (202) and a cron worker (app/scripts/snapshot_worker.php)\nexports the relation with ogr2ogr and uploads data.parquet + metadata.json.\nGET returns the job status. Super-user only.",
+                        "type": "string",
+                        "example": "0b8c2f2e-2f5a-4d9c-9d3a-1b2c3d4e5f60"
+                    },
+                    "status": {
+                        "type": "string",
+                        "example": "pending"
+                    },
+                    "_links": {
+                        "properties": {
+                            "self": {
+                                "type": "string",
+                                "example": "/api/v4/snapshots/0b8c2f2e-2f5a-4d9c-9d3a-1b2c3d4e5f60"
+                            }
+                        },
+                        "type": "object"
+                    }
+                },
+                "type": "object"
+            },
+            "SnapshotRequest": {
+                "description": "A request to snapshot a table or view to Parquet on S3.",
+                "required": [
+                    "schema",
+                    "relation"
+                ],
+                "properties": {
+                    "schema": {
+                        "title": "Schema",
+                        "description": "Schema of the relation.",
+                        "type": "string",
+                        "example": "geodanmark"
+                    },
+                    "relation": {
+                        "title": "Relation",
+                        "description": "Table or view name.",
+                        "type": "string",
+                        "example": "bygning"
+                    },
+                    "srs": {
+                        "title": "SRS",
+                        "description": "Optional EPSG code to reproject to. Omit to keep the native SRID.",
+                        "type": "integer",
+                        "example": 25832
+                    }
+                },
+                "type": "object"
+            },
+            "Snapshot": {
+                "description": "Status of a snapshot job.",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "example": "0f4c1b2e-..."
+                    },
+                    "schema": {
+                        "type": "string",
+                        "example": "geodanmark"
+                    },
+                    "relation": {
+                        "type": "string",
+                        "example": "bygning"
+                    },
+                    "srs": {
+                        "type": [
+                            "integer",
+                            "null"
+                        ],
+                        "example": 25832
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": [
+                            "pending",
+                            "running",
+                            "succeeded",
+                            "failed",
+                            "superseded"
+                        ]
+                    },
+                    "snapshot_date": {
+                        "description": "UTC date the export ran; the {date} segment of the relation snapshot read API.",
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date",
+                        "example": "2026-09-16"
+                    },
+                    "s3_path": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "example": "s3://gc2-parquet/prod/mydb/schema=geodanmark/relation=bygning/_gc2_snapshot_date=2026-09-15/"
+                    },
+                    "row_count": {
+                        "type": [
+                            "integer",
+                            "null"
+                        ],
+                        "example": 123456
+                    },
+                    "schema_version": {
+                        "description": "md5 fingerprint of relation_schema, for drift detection.",
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "example": "9e107d9d372bb6826bd81d3542a419d6"
+                    },
+                    "relation_schema": {
+                        "description": "Columns of the relation at snapshot time (name and PostgreSQL type).",
+                        "type": [
+                            "array",
+                            "null"
+                        ],
+                        "items": {
+                            "type": "object"
+                        },
+                        "example": [
+                            {
+                                "column_name": "gid",
+                                "data_type": "integer"
+                            },
+                            {
+                                "column_name": "the_geom",
+                                "data_type": "geometry(Point,25832)"
+                            }
+                        ]
+                    },
+                    "error": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "username": {
+                        "type": "string"
+                    },
+                    "created": {
+                        "type": "string",
+                        "format": "date-time"
+                    },
+                    "started": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time"
+                    },
+                    "finished": {
+                        "type": [
+                            "string",
+                            "null"
+                        ],
+                        "format": "date-time"
+                    }
+                },
+                "type": "object"
+            },
             "SqlRequest": {
                 "description": "Execute SQL statements. Supports SELECT, INSERT, UPDATE, DELETE, and MERGE (no DDL or transaction control).",
                 "required": [
@@ -7790,6 +8820,14 @@
             "name": "Privileges",
             "description": "Privileges"
         },
+        {
+            "name": "Snapshots",
+            "description": "Snapshots"
+        },
+        {
+            "name": "Scheduler",
+            "description": "Scheduler"
+        },
         {
             "name": "Search",
             "description": "Search"
@@ -7815,4 +8853,4 @@
             "description": "Wfs"
         }
     ]
-}
+}

package/dist/index.js

@@ -283,6 +283,10 @@ function normalizeJsonSchemaForMCP(schema) {
 }
 const tools = [];
 const operationMap = new Map();
+// Binary file endpoints: their tools answer with the file's URL and HEAD
+// metadata instead of the body — a Parquet file cannot travel through an MCP
+// text result.
+const BINARY_URL_TOOLS = new Set(["getRelationSnapshotData", "getRelationSnapshotFile"]);
 for (const [pathStr, pathItem] of Object.entries(apiSpec.paths)) {
     for (const [method, operation] of Object.entries(pathItem)) {
         if (method === "parameters")
@@ -357,7 +361,10 @@ for (const [pathStr, pathItem] of Object.entries(apiSpec.paths)) {
         }
         tools.push({
             name: operationId,
-            description: op.description || op.summary || `Execute ${method.toUpperCase()} ${pathStr}`,
+            description: (op.description || op.summary || `Execute ${method.toUpperCase()} ${pathStr}`) +
+                (BINARY_URL_TOOLS.has(operationId)
+                    ? " This tool returns the file's URL and metadata, not the binary body."
+                    : ""),
             inputSchema: {
                 type: "object",
                 properties,
@@ -467,20 +474,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             config.data = safeArgs.requestBody;
         }
     }
+    // Binary file tools issue a HEAD instead of a GET and report URL + metadata.
+    const binaryUrlTool = BINARY_URL_TOOLS.has(name);
+    if (binaryUrlTool)
+        config.method = "head";
     const sendRequest = () => axios({
         ...config,
         url,
         maxRedirects: 0,
         validateStatus: (status) => status < 400,
     });
-    const formatSuccess = (response) => ({
-        content: [
-            {
-                type: "text",
-                text: response.data != null ? JSON.stringify(response.data, null, 2) : response.statusText,
-            },
-        ],
-    });
+    const formatSuccess = (response) => {
+        if (binaryUrlTool) {
+            const h = response.headers ?? {};
+            const presigned = response.status === 302 ? h["location"] : undefined;
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            url,
+                            ...(presigned ? { presigned_url: presigned } : {}),
+                            content_type: h["content-type"] ?? null,
+                            size_bytes: h["content-length"] != null ? Number(h["content-length"]) : null,
+                            etag: h["etag"] ?? null,
+                            accept_ranges: h["accept-ranges"] ?? null,
+                            note: presigned
+                                ? "Redirect mode: fetch presigned_url directly — it is short-lived and needs no auth headers."
+                                : "The binary body is not returned through MCP. Read `url` directly with the same bearer token (HTTP Range supported), e.g. DuckDB: CREATE SECRET (TYPE http, BEARER_TOKEN '<token>'); SELECT * FROM read_parquet('<url>');",
+                        }, null, 2),
+                    }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: response.data != null ? JSON.stringify(response.data, null, 2) : response.statusText,
+                },
+            ],
+        };
+    };
     try {
         return formatSuccess(await sendRequest());
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centia-io/mcp-server",
-  "version": "1.0.19",
+  "version": "1.0.22",
   "publishConfig": {
     "access": "public"
   },

package/skills/centia-auth-model/SKILL.md

@@ -48,7 +48,7 @@ flow.signOut()       // clears tokens
 - Prerequisites: a default user must exist on the database (otherwise 404 `NO_DEFAULT_USER_FOUND`) and an OAuth client must be registered (`postClient`); unknown client → 401 `invalid_grant`, wrong secret → 401 `invalid_client`.
 - Use it for read-only/public UIs and for token-only endpoints (Feature, SQL, GraphQL, RPC) that need a bearer even for public data. Never grant the default user write or admin privileges to make a guest app "work".
 - In browsers use a **public** client so no secret ships in the bundle; switch to `CodeFlow` once the user signs in.
-- Errors are thrown as plain `Error` with status and response body, like the other auth flows — not `CentiaApiError`. `GuestFlow` ships in `@centia-io/sdk` >= 0.2.14 (unreleased as of 2026-09-11; latest is 0.2.13).
+- Errors are thrown as plain `Error` with status and response body, like the other auth flows — not `CentiaApiError`. `GuestFlow` ships in `@centia-io/sdk` >= 0.2.14.
 
 ## Server and CLI