@centia-io/mcp-server 1.0.15 → 1.0.17

package/skills/centia-openapi-docs/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: centia-openapi-docs
+description: OpenAPI and documentation fallback policy for Centia BaaS, including source priority, local caching workflow, and rules for docs-backed endpoint usage.
+---
+
+# OpenAPI and Docs Policy
+
+Use this skill when MCP/SDK are insufficient and HTTP contracts are needed.
+
+## Source priority
+
+Use this order:
+
+1. Local `openapi/openapi.json`
+2. URL from `CENTIA_OPENAPI_URL`
+3. User-provided OpenAPI JSON
+
+OpenAPI is the contract for described endpoints.
+
+## Fetch pattern
+
+If allowed and needed, fetch into local cache:
+
+```sh
+mkdir -p openapi
+if [ -n "$CENTIA_OPENAPI_URL" ] && [ ! -f "openapi/openapi.fetched.json" ]; then
+  curl -fsSL -H "Authorization: Bearer $CENTIA_ACCESS_TOKEN" "$CENTIA_OPENAPI_URL" -o openapi/openapi.fetched.json
+fi
+```
+
+## Documentation fallback
+
+Primary docs:
+
+- `https://centia.io/docs/intro`
+
+Optional local vendor mirror:
+
+```sh
+mkdir -p vendor
+if [ ! -d "vendor/centia-docs/docs" ]; then
+  git clone --depth 1 --filter=blob:none --sparse https://github.com/centia-io/website.git vendor/centia-docs
+  cd vendor/centia-docs
+  git sparse-checkout set docs
+  cd ../..
+fi
+```
+
+If clone fails (auth/network), use web docs directly.
+
+## Rules
+
+- Use docs-backed endpoints only when fully specified.
+- Do not invent undocumented payloads.
+- Document source URL for each HTTP fallback implementation.

package/skills/centia-privileges/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: centia-privileges
+description: Sub-user privileges and rights inheritance for Centia BaaS, including per-table privilege grants, group membership via user_group, transitive inheritance where the highest privilege wins, schema ownership, and layer authentication levels.
+---
+
+# Privileges and Rights Inheritance
+
+Use this skill when granting sub-users access to tables/layers, managing groups, or reasoning about which effective privilege a sub-user ends up with.
+
+## Model
+
+- Privileges are **per relation** (per `schema.table`), not schema-wide grants.
+- A grant maps a sub-user *or group* name to a level: `none` | `read` | `write` (API values; internally ranked none=0 < read=1 < read/write=2).
+- **Groups are themselves sub-users.** There is no separate group entity or membership endpoint — any sub-user name can act as a group.
+
+## Endpoints and MCP tools
+
+| Task | Route | MCP tool |
+|---|---|---|
+| Read grants for a table | `GET /api/v4/schemas/{s}/tables/{t}/privileges` | `getPrivileges` |
+| Set grants | `PATCH .../privileges` with `{subuser, privilege}` (one or array) | `patchPrivileges` |
+| Group membership | `user_group` field on `POST/PATCH/GET /api/v4/users` | `postUser` / `patchUser` / `getUser` |
+
+`user_group` is a **JSON array of group names** (e.g. `["editors", "gis_admins"]`). A JSON-array *string* is accepted for back-compat; `null` clears membership; GET returns a decoded array (or null).
+
+## Inheritance — highest privilege wins
+
+Evaluation is fully server-side:
+
+1. The full inheritance chain is resolved: the sub-user plus all ancestor groups, transitively (groups can belong to groups; breadth-first, diamond/cycle-safe).
+2. Effective privilege on a table = the **highest** level found among the sub-user's own grant and every group in the chain.
+
+Example: `joe` has `read` directly, is member of `editors` which has `write` → joe's effective privilege is `write`.
+
+This applies to token auth, Basic-auth WFS/OWS, and SQL authorization alike.
+
+## Schema ownership
+
+A sub-user is **owner** of a schema if their own name — or any group in their transitive chain — equals the schema name. Owners bypass all privilege checks (full read/write on every layer in that schema). This is how schema-wide access is inherited: put the sub-user (directly or via intermediate groups) in a group named after the schema.
+
+## Layer authentication levels
+
+Orthogonal to per-user grants, each layer has an `authentication` level (capitalized values) deciding *when* grants are enforced:
+
+| Level | Anonymous | Authenticated sub-user |
+|---|---|---|
+| `Read/write` | No read, no write (403) | Read requires privilege ≠ `none`; write requires `write` (owner bypasses) |
+| `Write` | Read allowed | Read allowed for all; write requires `write` (owner bypasses) |
+| `Read` / `None` | Read open | No per-user enforcement on read |
+
+OGC endpoints are merged, database-qualified routes (`/api/v4/ows/schema/{schema}/database/{database}`, `/api/v4/wfs/schema/{schema}/database/{database}/srs/...`; the old token-only variants are removed). Auth is decided per request: Bearer token (must match `{database}`, else 401 — never a silent anonymous downgrade), anonymous for publicly readable layers, or an HTTP Basic challenge for protected layers. WFS-T always requires credentials with `write`.
+
+## Common mistakes
+
+| Mistake | Reality |
+|---|---|
+| Expecting a schema-wide grant endpoint | Grants are per table; schema-wide access only via ownership (group named = schema) |
+| `PATCH /users/{name}` without `default_user` | The flag is **reset to false** when omitted — always send it explicitly |
+| Promoting a new default user first | Only one default user per parent db (partial unique index) → 23505; demote the old one first |
+| Treating groups as a separate concept | Groups are sub-users; membership lives on the member's `user_group` field |
+| Assuming grants alone control access | The layer's `authentication` level decides whether grants are even consulted |
+| Expecting `200` from `patchPrivileges`/`patchUser` | Provisioning PATCH returns `303 See Other` (see `centia-provisioning`) |
+
+Spec quirk: the `Privilege` schema's `required` list names `privileges` (plural) but the actual property is singular `privilege` — use the singular key.
+
+Auth context selection (tokens, OAuth, service vs browser) is covered in `centia-auth-model`.

package/skills/centia-provisioning/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: centia-provisioning
+description: Provisioning and schema lifecycle guidance for Centia BaaS, including schema/table/column/index/constraint operations, migration structure, SQL API limits, and destructive-change safety.
+---
+
+# Provisioning Rules
+
+Use this skill for schema changes, migrations, seed data, and platform setup.
+
+## Scope
+
+Provisioning includes:
+
+- schemas
+- tables
+- columns
+- indexes
+- constraints
+- policies
+- relations
+- relation metadata (titles, descriptions, tags, field aliases)
+- seed data
+- migrations
+
+Provisioning is not runtime logic.
+
+## Hard rules
+
+- Preferred execution order: MCP tools, then OpenAPI, then docs-backed endpoints.
+- Runtime app code must never call provisioning endpoints.
+- Schema changes happen only in provisioning/codegen flows.
+
+## PATCH returns 303 See Other
+
+All provisioning PATCH endpoints return `303 See Other` with a `Location` header pointing to the updated resource. HTTP clients that automatically follow redirects will receive an unexpected `200 OK` from the subsequent GET instead of the expected `303`.
+
+External clients **must** disable automatic redirect-following:
+
+- `fetch`: `{ redirect: 'manual' }` in `RequestInit`
+- `axios`: `{ maxRedirects: 0 }` (catch the resulting error)
+- `curl`: omit the `-L` flag
+- Postman: disable "Automatically follow redirects" in Settings
+
+The SDK already handles this via `redirect: 'manual'` in all fetch calls.
+
+## SQL dialect and API limits
+
+- SQL dialect is PostgreSQL with PostGIS enabled.
+- SQL API accepts only: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `MERGE`.
+- DDL and transaction control are not accepted by SQL API; use provisioning tools.
+
+## Provisioning output structure
+
+Store artifacts in:
+
+- `provision/`
+- `migrations/`
+- `schema/plan.json`
+- `schema/plan.md`
+
+Example runners:
+
+```sh
+npx tsx provision/apply.ts
+npx tsx migrations/001_create_tables.ts
+```
+
+## Safety for destructive operations
+
+Before destructive operations, present:
+
+- method
+- MCP tool or endpoint
+- purpose
+
+Proceed only with explicit user confirmation.
+
+Destructive includes:
+
+- `DROP TABLE`
+- `TRUNCATE`
+- column deletion
+- policy overwrite
+- `DELETE` without safe filter
+- `deleteTable`, `deleteColumn`, `deleteSchema`, `deleteConstraint`, `deleteIndex`
+
+## Project structure target
+
+```txt
+src/
+  baas/
+    client.ts
+    http.ts
+    types.ts
+  features/
+
+provision/
+schema/
+migrations/
+docs/
+
+.env.example
+openapi/
+vendor/
+```

package/skills/centia-realtime/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: centia-realtime
+description: Realtime events via WebSocket for Centia BaaS using @centia-io/sdk, including broadcast connections, subscriptions with shapes, event handling, and enabling table-level change events.
+---
+
+# Realtime Events
+
+Use this skill for WebSocket-based realtime database change events.
+
+## Hard rules
+
+- Use `Ws` from `@centia-io/sdk` for all realtime connections.
+- Do not implement raw WebSocket connections in runtime app code.
+- Never hardcode tokens in connection URLs.
+- Always use `encodeURIComponent` if building URLs manually (the SDK handles this).
+
+## Architecture
+
+- WebSocket endpoint: `wss://event.centia.io/`
+- Auth: JWT token passed as query parameter.
+- Server validates the token and enforces per-relation access for sub-users.
+- Events are batched (10 notifications or 2 seconds, whichever comes first).
+
+## SDK bootstrap
+
+```ts
+import { Ws } from '@centia-io/sdk';
+
+const ws = new Ws({
+    host: 'wss://event.centia.io',
+    rels: 'schema.table1,schema.table2',  // optional: broadcast filter
+    reconnect: true,                       // default: true
+    reconnectInterval: 3000,               // default: 3000ms
+});
+
+ws.connect();
+```
+
+### Options
+
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `host` | string | yes | - | WebSocket endpoint URL |
+| `rels` | string | no | - | Comma-separated relations for broadcast filtering |
+| `wsClient` | unknown | no | `WebSocket` | Custom WebSocket implementation (e.g. `ws` for Node) |
+| `reconnect` | boolean | no | `true` | Auto-reconnect on disconnect |
+| `reconnectInterval` | number | no | `3000` | Reconnect delay in ms |
+
+## Event listeners
+
+The `Ws` class uses a typed event system. `on()` returns an unsubscribe function.
+
+```ts
+ws.on('open', () => { /* connected */ });
+
+ws.on('batch', (msg) => {
+    // msg.db, msg.batch
+    for (const [rel, data] of Object.entries(msg.batch[msg.db])) {
+        if (data.INSERT) { /* handle inserts */ }
+        if (data.UPDATE) { /* handle updates */ }
+        if (data.DELETE) { /* handle deletes */ }
+        if (data.full_data) { /* full row data */ }
+    }
+});
+
+ws.on('subscription_ack', (msg) => {
+    // msg.id — matches the subscription id
+});
+
+ws.on('error', (msg) => {
+    // msg.error: 'missing_token' | 'invalid_token' | 'not_allowed'
+    // msg.message: human-readable
+});
+
+ws.on('close', ({ code, reason }) => { /* disconnected */ });
+
+// Unsubscribe
+const unsub = ws.on('batch', handler);
+unsub(); // removes listener
+```
+
+## Subscriptions with shapes
+
+Subscriptions provide server-side filtering so the client only receives matching events. Send after the connection is open.
+
+```ts
+ws.on('open', () => {
+    ws.subscribe({
+        id: 'active-users',
+        schema: 'public',
+        rel: 'users',
+        where: "status = 'active' AND age >= 18",
+        columns: 'id,name,email',
+        op: 'UPDATE',
+    });
+});
+```
+
+### Subscription fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | string | yes | Client-chosen identifier |
+| `schema` | string | yes | Database schema name |
+| `rel` | string | yes | Table name |
+| `where` | string | no | SQL-like filter on `full_data` rows |
+| `columns` | string | no | Comma-separated column projection |
+| `op` | string | no | Limit to `INSERT`, `UPDATE`, or `DELETE` |
+
+### Where syntax
+
+Supports: `=`, `!=`, `<>`, `>`, `<`, `>=`, `<=`, `AND`, `OR`, parentheses, `IN`/`NOT IN`, `LIKE`/`ILIKE`.
+
+### Multiple subscriptions
+
+A single client can register multiple subscriptions:
+
+```ts
+ws.subscribe({ id: 'sub1', schema: 'public', rel: 'orders' });
+ws.subscribe({ id: 'sub2', schema: 'public', rel: 'users', op: 'INSERT' });
+```
+
+## Enabling table events (provisioning)
+
+To emit change events for a table, enable `emit_events` via the events endpoint. This is a provisioning operation.
+
+Use MCP tool `postEvents` or HTTP:
+
+```http
+PATCH https://api.centia.io/api/v4/schemas/{schema}/tables/{table}/events
+Content-Type: application/json
+Authorization: Bearer <token>
+
+{
+  "emit_events": true
+}
+```
+
+## Broadcast vs subscriptions
+
+| Feature | Broadcast (legacy) | Subscriptions |
+|---|---|---|
+| Setup | Pass `rels` in constructor | Call `ws.subscribe()` after connect |
+| Filtering | Client-side only | Server-side (where, columns, op) |
+| Use case | Simple monitoring | Production apps needing efficiency |
+
+Prefer subscriptions for new code. Broadcast is supported but sends all events for matched relations.
+
+## Node.js usage
+
+Pass a WebSocket implementation for non-browser environments:
+
+```ts
+import WebSocket from 'ws';
+import { Ws } from '@centia-io/sdk';
+
+const ws = new Ws({
+    host: 'wss://event.centia.io',
+    wsClient: WebSocket,
+});
+```
+
+## Lifecycle
+
+```ts
+ws.connect();           // start connection
+ws.connected;           // boolean — check state
+ws.send('SELECT 1');    // send raw message
+ws.disconnect();        // close and stop reconnecting
+```
+
+## Exported types
+
+All types are available from `@centia-io/sdk`:
+
+```ts
+import type {
+    WsOptions,
+    WsMessage,
+    BatchMessage,
+    TableBatch,
+    SubscriptionAckMessage,
+    WsErrorMessage,
+    SubscriptionRequest,
+} from '@centia-io/sdk';
+```

package/skills/centia-runtime-sdk/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: centia-runtime-sdk
+description: Runtime application guidance for Centia BaaS using @centia-io/sdk, including SDK client initialization, GraphQL/JSON-RPC/SQL method selection, HTTP fallback boundaries, and frontend tooling defaults.
+---
+
+# Runtime SDK Rules
+
+Use this skill for JS/TS runtime application work.
+
+## Hard rules
+
+- Use `@centia-io/sdk` for runtime access.
+- Do not use direct REST calls in runtime app code.
+- If SDK lacks needed functionality, implement a documented fallback in `src/baas/http.ts`.
+
+## Query method selection
+
+Choose in this order:
+
+1. GraphQL (`Gql`) for straightforward CRUD, filtering, pagination, nested relations.
+2. JSON-RPC (`createApi<T>()` or `Rpc`) for reusable complex SQL (joins, CTEs, aggregations).
+3. SQL (`Sql` and `createSqlBuilder`) as last resort for runtime-dynamic queries.
+
+## SDK bootstrap
+
+Create shared clients in `src/baas/client.ts`.
+
+Prefer exports:
+
+- `Sql`
+- `Rpc`
+- `Gql`
+- `createApi`
+- `createSqlBuilder`
+- `CodeFlow`, `PasswordFlow`, `SignUp` (by runtime context)
+
+## GraphQL notes
+
+Auto-generated naming conventions by table:
+
+- Select: `get[TableName]`
+- Insert: `insert[TableName]`
+- Update: `update[TableName]`
+- Delete: `delete[TableName]`
+
+Filtering operators:
+
+- Comparison: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `like`, `ilike`
+- Logical: `and`, `or`, `not`
+
+## SQL builder pattern
+
+Prefer typed SQL builder for dynamic conditions:
+
+```ts
+const b = createSqlBuilder(schema);
+let req = b.table("logs").select(["id", "message"]);
+if (level) req = req.andWhere({ level });
+if (since) req = req.andWhere({ created_at: { gte: since } });
+const rows = (await sql.exec(req.toSql())).data;
+```
+
+## HTTP fallback layer
+
+File: `src/baas/http.ts`
+
+Rules:
+
+- Centralize headers.
+- Use typed payloads.
+- Prevent token leakage.
+- Add source comments for each fallback endpoint.
+
+Comment template:
+
+```ts
+// Fallback to HTTP: not supported in @centia-io/sdk yet
+// Source: https://centia.io/docs/...
+```
+
+## Web app defaults when scaffolding
+
+Use these defaults only if project has no existing conventions:
+
+- Package manager: `pnpm`
+- Build tool: `Vite`
+- Framework: React + TypeScript
+- Styling: Tailwind CSS
+- Routing: React Router
+
+Do not mix package managers.
+
+## Code quality
+
+- Prefer TypeScript strict mode.
+- Centralize schema and table names.
+- Avoid magic strings.
+- Handle API errors explicitly.

package/skills/centia-types-formats/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: centia-types-formats
+description: PostgreSQL and PostGIS type guidance for Centia BaaS, including SQL parameter casts, type_hints, type_formats, and supported output formats for SQL and JSON-RPC responses.
+---
+
+# Types and Formats
+
+Use this skill for SQL typing, RPC type hints, and output format decisions.
+
+## SQL type system baseline
+
+Use PostgreSQL types (including PostGIS-enabled environments).
+
+Common groups:
+
+- Numeric: `smallint`, `integer`, `bigint`, `numeric`, `real`, `double precision`
+- Character: `varchar(n)`, `char(n)`, `text`
+- Boolean: `boolean`
+- JSON: `json`, `jsonb`
+- Date/time: `date`, `time`, `timetz`, `timestamp`, `timestamptz`, `interval`
+- Range: `int4range`, `int8range`, `numrange`, `daterange`, `tsrange`, `tstzrange`
+- Arrays: append `[]` (for example `integer[]`, `text[]`)
+
+## SQL parameter syntax
+
+Centia uses **PDO-style named parameters** (`:name`). Positional placeholders (`$1`, `$2`, …) are NOT supported and fail with `SQLSTATE[HY093]: Invalid parameter number`.
+
+Pass a single-object `params` array where keys match the placeholder names:
+
+```json
+{
+  "q": "SELECT * FROM schema.relation WHERE id = :id AND code = :code",
+  "params": [{ "id": 42, "code": "A1" }]
+}
+```
+
+Always cast parameters when types are ambiguous or for JSON-RPC type inference:
+
+```sql
+SELECT :name::text, :age::integer, :joined::date
+```
+
+## type_hints
+
+Use `type_hints` when server-side inference is ambiguous.
+
+Example:
+
+```json
+{ "date": "timestamptz", "days": "integer" }
+```
+
+## type_formats
+
+Use `type_formats` to format temporal output columns.
+
+Example:
+
+```json
+{ "date": "D M d Y", "time": "H:i:s T" }
+```
+
+## Output formats (SQL and JSON-RPC)
+
+Supported through `output_format`:
+
+- Standard: `json`, `geojson`, `csv`, `excel`, `ogr/[format]`
+- Streaming: `ndjson`, `ccsv`
+
+Rules:
+
+- Standard formats are single-response and capped at 100000 rows.
+- Streaming formats have no row cap and are suitable for large exports/pipelines.
+- Default format is `json` with `schema` and `data` fields.