ultipa-mcp 1.0.1

package/dist/helpers/import.js

@@ -0,0 +1,261 @@
+// Import helpers used by `import_data` in src/tools/dataplane.ts.
+// Kept separate so they're easy to unit-test and so dataplane.ts stays focused
+// on tool registrations.
+import { readFile } from "node:fs/promises";
+// Minimal RFC 4180-style CSV parser used by `import_data`'s CSV pass-through.
+// Handles quoted fields with delimiter/newlines inside, escaped quotes
+// (`""` → `"`), CRLF / LF line endings, UTF-8 BOM, and a missing trailing
+// newline. Defaults: delimiter = `,`, quote = `"`. Both single-character
+// overrides supported for TSV / semicolon CSV / Windows CSVs etc. For more
+// exotic formats (multi-char delimiter, leading metadata rows), the agent
+// should preprocess client-side and use canonical `nodes`/`edges` arrays.
+export function parseCsv(text, opts = {}) {
+    const delimiter = opts.delimiter ?? ",";
+    const quote = opts.quote ?? '"';
+    if (delimiter.length !== 1) {
+        throw new Error(`CSV delimiter must be a single character; got "${delimiter}".`);
+    }
+    if (quote.length !== 1) {
+        throw new Error(`CSV quote must be a single character; got "${quote}".`);
+    }
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    const rows = [];
+    let row = [];
+    let field = "";
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === quote) {
+                if (text[i + 1] === quote) {
+                    field += quote;
+                    i++;
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                field += c;
+            }
+        }
+        else if (c === quote) {
+            inQuotes = true;
+        }
+        else if (c === delimiter) {
+            row.push(field);
+            field = "";
+        }
+        else if (c === "\n") {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = "";
+        }
+        else if (c === "\r") {
+            // ignore; `\n` handles row break
+        }
+        else {
+            field += c;
+        }
+    }
+    if (field !== "" || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+// Coerce a raw CSV cell (always a string) into the requested type. Empty cells
+// become null. Unknown / passthrough types return the original string so the
+// server can do its own coercion if applicable.
+export function coerceCell(value, type) {
+    if (value === "")
+        return null;
+    if (!type)
+        return value;
+    switch (type.toUpperCase()) {
+        case "INT":
+        case "INTEGER":
+        case "BIGINT": {
+            const n = parseInt(value, 10);
+            if (Number.isNaN(n))
+                throw new Error(`Cannot coerce "${value}" to INT`);
+            return n;
+        }
+        case "FLOAT":
+        case "DOUBLE": {
+            const f = parseFloat(value);
+            if (Number.isNaN(f))
+                throw new Error(`Cannot coerce "${value}" to FLOAT`);
+            return f;
+        }
+        case "BOOL":
+        case "BOOLEAN": {
+            const v = value.trim().toLowerCase();
+            if (["true", "t", "yes", "y", "1"].includes(v))
+                return true;
+            if (["false", "f", "no", "n", "0"].includes(v))
+                return false;
+            throw new Error(`Cannot coerce "${value}" to BOOL`);
+        }
+        default:
+            // STRING, TIMESTAMP, DATE, ZONED_DATETIME, etc. — pass through.
+            return value;
+    }
+}
+// Convert parsed CSV content + companion fields into canonical NodeData[] /
+// EdgeData[]. Shared by inline `csv` content mode and `filePath` (CSV files).
+export function csvToCanonical(content, opts) {
+    if (!!opts.fromColumn !== !!opts.toColumn) {
+        throw new Error("CSV edge mode requires BOTH `csvFromColumn` and `csvToColumn`.");
+    }
+    const isEdgeMode = !!opts.fromColumn;
+    const rows = parseCsv(content, {
+        delimiter: opts.delimiter,
+        quote: opts.quote,
+    });
+    const header = rows[0];
+    if (!header)
+        throw new Error("CSV is empty (no header row).");
+    const dataRows = rows
+        .slice(1)
+        .filter((r) => !(r.length === 1 && r[0] === ""));
+    const colIdx = (name) => {
+        const i = header.indexOf(name);
+        if (i < 0)
+            throw new Error(`CSV column "${name}" not found in header: ${header.join(", ")}`);
+        return i;
+    };
+    const idIdx = opts.idColumn ? colIdx(opts.idColumn) : -1;
+    const fromIdx = isEdgeMode ? colIdx(opts.fromColumn) : -1;
+    const toIdx = isEdgeMode ? colIdx(opts.toColumn) : -1;
+    const excluded = new Set([idIdx, fromIdx, toIdx].filter((i) => i >= 0));
+    const propMapping = opts.properties
+        ? opts.properties.map((m) => ({
+            property: m.property,
+            colIdx: colIdx(m.column),
+            type: m.type,
+        }))
+        : header
+            .map((col, i) => excluded.has(i) ? null : { property: col, colIdx: i })
+            .filter((m) => m !== null);
+    const buildProps = (row) => {
+        const props = {};
+        for (const m of propMapping) {
+            props[m.property] = coerceCell(row[m.colIdx] ?? "", m.type);
+        }
+        return props;
+    };
+    if (isEdgeMode) {
+        const edges = dataRows.map((row, i) => {
+            const fromNodeId = row[fromIdx];
+            const toNodeId = row[toIdx];
+            if (!fromNodeId || !toNodeId)
+                throw new Error(`Row ${i + 2}: missing _from / _to (both required).`);
+            const edge = {
+                label: opts.label,
+                fromNodeId,
+                toNodeId,
+                properties: buildProps(row),
+            };
+            if (idIdx >= 0 && row[idIdx])
+                edge.id = row[idIdx];
+            return edge;
+        });
+        return { edges, rowCount: edges.length };
+    }
+    const nodes = dataRows.map((row) => {
+        const node = {
+            labels: [opts.label],
+            properties: buildProps(row),
+        };
+        if (idIdx >= 0 && row[idIdx])
+            node.id = row[idIdx];
+        return node;
+    });
+    return { nodes, rowCount: nodes.length };
+}
+// Convert JSON / JSONL content into canonical NodeData[] / EdgeData[].
+// Auto-detects shape: `NodeData[]` (labels array on first item), `EdgeData[]`
+// (fromNodeId/toNodeId on first item), or `{nodes, edges}` mixed object.
+export function jsonToCanonical(content, isJsonl) {
+    let parsed;
+    if (isJsonl) {
+        parsed = content
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line !== "")
+            .map((line, i) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch (e) {
+                throw new Error(`Invalid JSON on line ${i + 1}: ${e?.message ?? String(e)}`);
+            }
+        });
+    }
+    else {
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (e) {
+            throw new Error(`Invalid JSON: ${e?.message ?? String(e)}`);
+        }
+    }
+    if (Array.isArray(parsed)) {
+        if (parsed.length === 0)
+            throw new Error("JSON array is empty.");
+        const first = parsed[0];
+        if (first &&
+            typeof first === "object" &&
+            "fromNodeId" in first &&
+            "toNodeId" in first) {
+            return { edges: parsed };
+        }
+        if (first && typeof first === "object" && Array.isArray(first.labels)) {
+            return { nodes: parsed };
+        }
+        throw new Error(`Cannot detect JSON shape. Array items must be NodeData ({labels, properties, id?}) or EdgeData ({label, fromNodeId, toNodeId, properties, id?}). First item: ${JSON.stringify(first).slice(0, 200)}`);
+    }
+    if (parsed && typeof parsed === "object" && (parsed.nodes || parsed.edges)) {
+        return {
+            nodes: parsed.nodes,
+            edges: parsed.edges,
+        };
+    }
+    throw new Error("JSON root must be NodeData[] / EdgeData[] / {nodes, edges}.");
+}
+// Dispatch a host file path to the right parser by extension. CSV requires
+// `csvLabel` + companion fields; JSON / JSONL parse straight into canonical
+// shape with no extra config.
+export async function loadFilePath(path, csvOpts) {
+    const ext = path.toLowerCase().split(".").pop();
+    let content;
+    try {
+        content = await readFile(path, "utf-8");
+    }
+    catch (e) {
+        throw new Error(`Cannot read file "${path}": ${e?.message ?? String(e)}. Path must be readable by the MCP process (typically the user's local machine for stdio MCPs).`);
+    }
+    if (ext === "csv") {
+        if (!csvOpts.label) {
+            throw new Error("CSV `filePath` requires `csvLabel` (the node or edge label).");
+        }
+        const { nodes, edges, rowCount } = csvToCanonical(content, {
+            label: csvOpts.label,
+            idColumn: csvOpts.idColumn,
+            fromColumn: csvOpts.fromColumn,
+            toColumn: csvOpts.toColumn,
+            properties: csvOpts.properties,
+            delimiter: csvOpts.delimiter,
+            quote: csvOpts.quote,
+        });
+        return { nodes, edges, format: "csv", rowCount };
+    }
+    if (ext === "json" || ext === "jsonl") {
+        const { nodes, edges } = jsonToCanonical(content, ext === "jsonl");
+        return { nodes, edges, format: ext };
+    }
+    throw new Error(`Unsupported file extension ".${ext}" for "${path}". Supported: .csv, .json, .jsonl`);
+}

package/dist/helpers/progress.d.ts

@@ -0,0 +1 @@
+export declare function makeProgressReporter(extra: any): ((step: string, status: string | undefined) => Promise<void>) | undefined;

package/dist/helpers/progress.js

@@ -0,0 +1,16 @@
+export function makeProgressReporter(extra) {
+    const token = extra?._meta?.progressToken;
+    if (token === undefined || token === null) {
+        console.error(`[ultipa-mcp] tool invoked WITHOUT _meta.progressToken — progress notifications will not be sent. Client cannot render mid-call progress.`);
+        return undefined;
+    }
+    console.error(`[ultipa-mcp] progressToken received: ${JSON.stringify(token)} — will stream notifications/progress.`);
+    let tick = 0;
+    return async (step, status) => {
+        const message = status ? `${step} (status: ${status})` : step;
+        await extra.sendNotification({
+            method: "notifications/progress",
+            params: { progressToken: token, progress: ++tick, message },
+        });
+    };
+}

package/dist/helpers/wait.d.ts

@@ -0,0 +1,8 @@
+export declare const STATUS_IN_TRANSITION: Set<string>;
+export type WaitOpts = {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onProgress?: (step: string, status: string | undefined) => void | Promise<void>;
+};
+export declare function waitForSettled(id: string, target: "running" | "paused" | "deleted", opts?: WaitOpts): Promise<any>;
+export declare function waitForBackup(instanceId: string, backupId: string, opts?: WaitOpts): Promise<any>;

package/dist/helpers/wait.js

@@ -0,0 +1,79 @@
+// Why two fields (status + progressStep)?
+//
+// Ultipa Cloud has no job API — state-change endpoints (resume, restart, etc.)
+// return 200 immediately and the work continues in the background. The polling
+// target is the instance object on /v1/instances/:id, but the transition
+// signal requires reading BOTH:
+//
+//   - `status`: provisioning | running | paused | suspended | error |
+//     deleting | upgrading | deleted. The first three are themselves
+//     in-transition values.
+//   - `progressStep`: a non-empty string ALWAYS means "in transition",
+//     regardless of `status`.
+//
+// Gotcha: resume-from-paused keeps `status: 'paused'` for the entire op — the
+// only signal it's in flight is `progressStep` (e.g. "Resuming instance...").
+// Same pattern for restart and set_log_level (status stays 'running', only
+// `progressStep` changes). Don't strip the `progressStep` guard thinking it's
+// redundant with `status` — it isn't.
+import { api } from "./api.js";
+export const STATUS_IN_TRANSITION = new Set([
+    "provisioning",
+    "upgrading",
+    "deleting",
+]);
+export async function waitForSettled(id, target, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 180_000;
+    const pollIntervalMs = opts.pollIntervalMs ?? 3000;
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    while (Date.now() < deadline) {
+        try {
+            last = await api(`/v1/instances/${id}`);
+        }
+        catch (e) {
+            if (target === "deleted" && String(e).includes("404")) {
+                await opts.onProgress?.("Instance deleted.", "deleted");
+                return { _id: id, status: "deleted" };
+            }
+            throw e;
+        }
+        const status = last?.status;
+        const progressStep = last?.progressStep ?? "";
+        const inTransition = progressStep !== "" ||
+            (status ? STATUS_IN_TRANSITION.has(status) : false);
+        if (!inTransition) {
+            if (status === target)
+                return last;
+            if (status === "error" || status === "suspended") {
+                throw new Error(`Instance ${id} settled on "${status}" (failure). Last state: ${JSON.stringify(last)}`);
+            }
+            throw new Error(`Instance ${id} settled on "${status}", expected "${target}". Last state: ${JSON.stringify(last)}`);
+        }
+        await opts.onProgress?.(progressStep || `Waiting for status "${target}"...`, status);
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new Error(`Timed out after ${timeoutMs}ms waiting for instance ${id} to reach "${target}". Last status: "${last?.status}", progressStep: "${last?.progressStep ?? ""}".`);
+}
+export async function waitForBackup(instanceId, backupId, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 600_000;
+    const pollIntervalMs = opts.pollIntervalMs ?? 5000;
+    const deadline = Date.now() + timeoutMs;
+    let backup = null;
+    while (Date.now() < deadline) {
+        const backups = (await api(`/v1/instances/${instanceId}/backups`));
+        backup = backups.find((b) => b?._id === backupId);
+        if (!backup) {
+            throw new Error(`Backup ${backupId} not found on instance ${instanceId} during wait.`);
+        }
+        const status = backup.status;
+        if (status === "completed")
+            return backup;
+        if (status === "failed") {
+            throw new Error(`Backup ${backupId} failed. Last state: ${JSON.stringify(backup)}`);
+        }
+        await opts.onProgress?.(`Backup ${status}...`, status);
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new Error(`Timed out after ${timeoutMs}ms waiting for backup ${backupId} on instance ${instanceId}. Last status: "${backup?.status}".`);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DEBUG, INSTANCE_HOST, INSTANCE_PASSWORD, INSTANCE_USER, hasModeA, hasModeB, } from "./helpers/env.js";
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { closeAllDataPlaneClients } from "./helpers/dataplane.js";
+import { registerAccountTools } from "./tools/account.js";
+import { registerInstanceTools } from "./tools/instances.js";
+import { registerMetricsTools } from "./tools/metrics.js";
+import { registerLogTools } from "./tools/logs.js";
+import { registerAlertTools } from "./tools/alerts.js";
+import { registerFirewallTools } from "./tools/firewall.js";
+import { registerBillingTools } from "./tools/billing.js";
+import { registerBackupTools } from "./tools/backups.js";
+import { registerDataPlaneTools } from "./tools/dataplane.js";
+import { registerDocsTools } from "./tools/docs.js";
+// Read package version at runtime so it stays in sync with package.json.
+// Works in both dev (tsx, file at src/index.ts) and prod (dist/index.js) since
+// package.json sits two levels up from either.
+const PKG_VERSION = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+// ── Fail-fast — neither mode configured, OR Direct mode partially configured ─
+const partialDirect = !hasModeB && (!!INSTANCE_HOST || !!INSTANCE_USER || !!INSTANCE_PASSWORD);
+if (!hasModeA && (!hasModeB || partialDirect)) {
+    const lines = [];
+    if (partialDirect) {
+        const missing = [];
+        if (!INSTANCE_HOST)
+            missing.push("ULTIPA_HOST");
+        if (!INSTANCE_USER)
+            missing.push("ULTIPA_USERNAME");
+        if (!INSTANCE_PASSWORD)
+            missing.push("ULTIPA_PASSWORD");
+        lines.push(`Direct instance config is incomplete — missing: ${missing.join(", ")}.`, "All three of ULTIPA_HOST, ULTIPA_USERNAME, ULTIPA_PASSWORD are required for Direct mode.", "");
+    }
+    lines.push("Ultipa MCP needs at least one auth mode configured:", "", "  Ultipa Cloud (manage instances and run GQL against any instance on the account):", "    ULTIPA_CLOUD_API_KEY=uc_...", "    Get a key at https://dbaas.ultipa.com → Settings → API Keys.", "", "  Direct instance (run GQL against one specific GQLDB instance, no Cloud account needed):", "    ULTIPA_HOST=host:port", "    ULTIPA_USERNAME=...", "    ULTIPA_PASSWORD=...", "    ULTIPA_GRAPH=...   (optional default graph)", "", "Either or both can be set. Set them in your MCP client's server config under `env`, or export them in the shell that launches the server.");
+    console.error(lines.join("\n"));
+    process.exit(1);
+}
+// ── Cleanup data-plane gRPC connections on shutdown ──────────────────────
+process.on("SIGINT", () => {
+    closeAllDataPlaneClients().finally(() => process.exit(0));
+});
+process.on("SIGTERM", () => {
+    closeAllDataPlaneClients().finally(() => process.exit(0));
+});
+// ── Server setup ─────────────────────────────────────────────────────────
+const server = new McpServer({ name: "ultipa-mcp", version: PKG_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+// ── ULTIPA_MCP_DEBUG=1: log every tool call name + latency to stderr ─────
+// Wrap server.tool() so every registered tool's handler is instrumented. Only
+// installed when DEBUG is on, so the default path stays free of overhead.
+if (DEBUG) {
+    const originalTool = server.tool.bind(server);
+    server.tool = (...args) => {
+        const handlerIdx = args.length - 1;
+        const handler = args[handlerIdx];
+        if (typeof handler === "function") {
+            const name = args[0];
+            args[handlerIdx] = async (...callArgs) => {
+                const start = Date.now();
+                try {
+                    const result = await handler(...callArgs);
+                    console.error(`[ultipa-mcp] ${name} ok ${Date.now() - start}ms`);
+                    return result;
+                }
+                catch (e) {
+                    console.error(`[ultipa-mcp] ${name} err ${Date.now() - start}ms ${e?.message ?? String(e)}`);
+                    throw e;
+                }
+            };
+        }
+        return originalTool(...args);
+    };
+}
+// ── Ultipa Cloud tools (control plane) ───────────────────────────────────
+if (hasModeA) {
+    registerAccountTools(server);
+    registerInstanceTools(server);
+    registerMetricsTools(server);
+    registerLogTools(server);
+    registerAlertTools(server);
+    registerFirewallTools(server);
+    registerBillingTools(server);
+    registerBackupTools(server);
+}
+// ── Data-plane tools + GQL docs lookup ───────────────────────────────────
+// Both gated by the same guard: lookup_docs is only useful when the
+// agent can actually compose and run queries, which requires a data-plane
+// target (either Direct instance or Ultipa Cloud with `id`).
+if (hasModeA || hasModeB) {
+    registerDataPlaneTools(server);
+    registerDocsTools(server);
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/instructions.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -0,0 +1,47 @@
+// Server-level instructions surfaced to the MCP client alongside the tool list.
+// These guide the agent's behavior across all calls.
+export const SERVER_INSTRUCTIONS = [
+    "**1. Two Paths to a GQLDB Instance**",
+    "a. **Cloud-managed instances** (set `ULTIPA_CLOUD_API_KEY` in MCP's env). Ultipa Cloud (https://dbaas.ultipa.com) is a DBaaS platfrom that fully manages GQLDB instances. Instances discoverable via `list_instances`. State-change tools (create, pause, resume, delete, etc.) operate on these. To connect to one of these instances, pass its `_id` as the `id` arg and get credientials via `get_instance_credentials`. Run queries on the instance with data-plane tools (`run_gql_query`, etc.).",
+    "b. **Directly-configured instance** (set `ULTIPA_HOST` + `ULTIPA_USERNAME` + `ULTIPA_PASSWORD` + optional `ULTIPA_GRAPH` in MCP's env). To connect to it, call a data-plane tool WITHOUT an `id` arg, the MCP routes the call to the env-configured instance.",
+    "",
+    "`list_instances` only sees Cloud instances. A Direct instance does NOT appear there but is reachable via data-plane tools without an `id` arg. If user asks about a self-managed / local instance, do not conclude 'not visible' from `list_instances` — call `test_connection` (omit `id`). If it returns `ok: true`, a Direct instance is reachable; if it errors with 'Direct instance is not configured', then only Ultipa Cloud is set up in this MCP.",
+    "",
+    "For Cloud instances, `list_instances` or `get_instance` does NOT return instance `adminPassword`. It's returned by `create_instance` — surface it to the user immediately after a create. For an existing instance, call `get_instance_credentials` (requires `ULTIPA_CLOUD_API_KEY` to have the `instances:credentials` permission).",
+    "",
+    "If `get_instance_credentials` fails on permissions, the recovery options are: (1) copy the password from https://dbaas.ultipa.com → Instance Details page, (2) regenerate the API key with the `instances:credentials` permission from https://dbaas.ultipa.com → Settings → API Keys, or (3) only when the user explicitly asks to rotate the password, call `reset_admin_password`.",
+    "",
+    "**2. Graph Query and Analytics**",
+    '**Use `lookup_docs` aggressively.** Training-time knowledge of Ultipa GQLDB or GQL is often wrong on edges. For any Ultipa or GQL specific question — schema design, GQL syntax, function signatures, ontology features, algorithm catalog — call `lookup_docs` FIRST and use the returned markdown as ground truth instead of guessing. The tool\'s description and empty-call response list the curated entry points; call `lookup_docs({ topic: "?" })` for the full live index.',
+    "",
+    "The query language is **GQL** (ISO/IEC 39075 standard Graph Query Language). It is NOT UQL, Cypher, or GraphQL.",
+    "",
+    "To answer data questions against a graph (e.g. 'what's the max age of users', 'count books by author X'):",
+    "a. An instance can host multiple graphs (check via `list_graphs`) with one marked as 'current', and queries run on it. Before running a query, ensure you know which graph the user is now working with (`ULTIPA_GRAPH` set in env or another one).",
+    "b. If you don't already know the graph schema/structure, call `describe_schema`. Discover node/edge labels and properties before composing GQL.",
+    "c. When composing the GQL query, for any syntax you're not certain about, follow the `lookup_docs` rule above.",
+    "d. Run GQL query via `run_gql_query` and report the result in natural language.",
+    "e. If the first run returns zero rows or errors, the schema is probably mis-guessed. Re-check `describe_schema` and retry, don't keep guessing.",
+    "",
+    "For complex analytical questions ('find influential users', 'detect communities', 'graph embedding'), check whether a built-in graph algorithm or stored procedure fits BEFORE composing custom GQL. They are dramatically faster on large graphs and can do things normal GQL query cannot achieve. Discovery:",
+    "- **Built-in algorithms** (run via `run_algo`): `lookup_docs('graph-algorithms/introduction')` for the algo catalog by category, then `lookup_docs('graph-algorithms/<category>/<algorithm>')` for one algorithm details (e.g. `centrality/pagerank`, `community-detection/louvain`). If needs to further process algo results, you may combine algo with other GQL statements and run via `run_gql_query`.",
+    "- **Stored procedures**: to call a procedure, use `run_gql_query` with `CALL <procedureName>(...)` (list available with `SHOW PROCEDURES`; see `lookup_docs('stored-procedures/calling-procedures')`). To **create** a procedure, use `write_procedure` — the procedure body has its own grammar (NOT GQL), so always `lookup_docs('stored-procedures/procedure-body/procedure-body-language')` first.",
+    "",
+    "**3. Data Writing Options",
+    "BEFORE choosing a tool to use, consider:",
+    "- If user **wrote out a small literal record in-conversation** (e.g. 'add a User node with name=Alice') → use `write_data` with hand-composed GQL.",
+    "- If user **attached / uploaded / pasted ANY file with row data** (csv, json, jsonl, graphml, tsv, pasted table) → MUST use `import_data`. **CRITICAL:** You MUST NOT compose `INSERT` statements row-by-row from file rows. `write_data` is for hand-composed GQL only — not for file-derived data. This rule overrides whatever INSERT-shaped reflex you have from training data.",
+    "If user has **large imports** (thousands of rows) or **other data sources** (SQL databases, other graph platforms, big-data systems) → suggest Ultipa Manager → Data Integration (UI wizard, built into Manager — Cloud instances open via `managerUrl`) or **Ultipa Transporter** (batch ETL CLI, https://www.ultipa.com/docs/tools/transporter).",
+    "",
+    "4. Improve Query Performance",
+    "If queries on a large graph are slow, suggest performance options to the user before just retrying:",
+    "- **Index** accelerate property filtering in predicates, created via `CREATE INDEX` (run through `run_gql_query`, syntax in `lookup_docs('gql/query-acceleration/index')`). For text search use `CREATE FULLTEXT INDEX` (`lookup_docs('gql/query-acceleration/fulltext-index')`). **Do NOT create indexes without explicit user confirmation** — each index costs storage and slows writes, so wrong indexes are net-negative.",
+    "- **Enable Computing Engine** for analytical / heavy workloads (graph algorithms like PageRank / community detection, multi-hop traversals, heavy aggregations). It's an instance-level add-on. Details in `lookup_docs('computing-engine/introduction')`.",
+    "",
+    "5. Connection Options",
+    "If user asks how to connect to an instance, refer the options below:",
+    "a.. **Ultipa Manager.** If it's a Cloud instance, open the instance's `managerUrl` in a browser. Easiest first-touch — gives a query editor, schema view, metrics, etc.",
+    "b. **Drivers.** Include Python, Java, Go, and . See https://www.ultipa.com/docs/drivers.",
+    "c. **Ultipa CLI.** A command-line tool for running queries. See https://www.ultipa.com/docs/tools/cli.",
+    "",
+].join("\n");

package/dist/tools/account.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAccountTools(server: McpServer): void;

package/dist/tools/account.js

@@ -0,0 +1,4 @@
+import { api, json } from "../helpers/api.js";
+export function registerAccountTools(server) {
+    server.tool("get_account", "Get the authenticated account's profile (email, name, balance flags, billing-related metadata). Useful as a 'who am I?' check or to surface account-wide info to the user.", {}, async () => json(await api("/v1/account")));
+}

package/dist/tools/alerts.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAlertTools(server: McpServer): void;

package/dist/tools/alerts.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+import { api, json } from "../helpers/api.js";
+export function registerAlertTools(server) {
+    server.tool("list_alerts", "List all alerts across the account's instances.", {}, async () => json(await api("/v1/instances/alerts")));
+    server.tool("list_instance_alerts", "List alerts for a single instance (all statuses).", { id: z.string().describe("The instance ID") }, async ({ id }) => json(await api(`/v1/instances/${id}/alerts`)));
+}

package/dist/tools/backups.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBackupTools(server: McpServer): void;

package/dist/tools/backups.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { api, json } from "../helpers/api.js";
+import { waitForSettled, waitForBackup } from "../helpers/wait.js";
+import { makeProgressReporter } from "../helpers/progress.js";
+export function registerBackupTools(server) {
+    server.tool("list_backups", "List all backups for an instance. Each backup has `_id`, `status` (`in_progress` | `completed` | `failed` | `restoring`), `createdAt`, and storage details.", { id: z.string().describe("The instance ID") }, async ({ id }) => json(await api(`/v1/instances/${id}/backups`)));
+    server.tool("create_backup", "Trigger an on-demand backup of an instance. Blocks until the backup reaches `completed` (or throws on `failed`). Default timeout 10 min — large instances can take longer; raise via `timeoutMs` if needed.", {
+        id: z.string().describe("The instance ID"),
+        timeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .default(600_000)
+            .describe("Max wait, in milliseconds. Default 600000 (10 min)."),
+    }, async ({ id, timeoutMs }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        const backup = (await api(`/v1/instances/${id}/backups`, {
+            method: "POST",
+        }));
+        try {
+            return json(await waitForBackup(id, backup._id, { timeoutMs, onProgress }));
+        }
+        catch (e) {
+            throw new Error(`Backup ${backup._id} WAS triggered on instance ${id} but waiting for "completed" failed: ${e?.message ?? e}. Do NOT call create_backup again — that would queue a duplicate backup. Call list_backups(id="${id}") to poll the current backup's status, or just wait and check again later.`);
+        }
+    });
+    server.tool("restore_backup", "Restore an instance from one of its completed backups. **Destructive: overwrites the instance's current data.** Blocks until the restore completes and the instance is back to 'running' (status stays 'running' throughout — only `progressStep` ('Restoring backup...') indicates the work). Default timeout 10 min.", {
+        id: z.string().describe("The instance ID"),
+        backupId: z
+            .string()
+            .describe("The backup ID to restore from (must belong to this instance and have status 'completed')"),
+    }, async ({ id, backupId }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        await api(`/v1/instances/${id}/restore`, {
+            method: "POST",
+            body: { backupId },
+        });
+        return json(await waitForSettled(id, "running", {
+            onProgress,
+            timeoutMs: 600_000,
+        }));
+    });
+    server.tool("set_backup_schedule", "Set or update an automated backup schedule on an instance. Synchronous; returns the updated instance. For `weekly`, `dayOfWeek` is required (0 = Sunday).", {
+        id: z.string().describe("The instance ID"),
+        frequency: z
+            .enum(["daily", "weekly"])
+            .describe("How often the backup should run"),
+        UTC_hour: z
+            .number()
+            .int()
+            .min(0)
+            .max(23)
+            .describe("Hour-of-day (UTC) at which to run, 0–23"),
+        dayOfWeek: z
+            .number()
+            .int()
+            .min(0)
+            .max(6)
+            .optional()
+            .describe("Day-of-week 0–6 (0 = Sunday). Required when frequency is 'weekly'."),
+    }, async ({ id, frequency, UTC_hour, dayOfWeek }) => {
+        if (frequency === "weekly" && dayOfWeek === undefined) {
+            throw new Error("dayOfWeek is required when frequency is 'weekly'.");
+        }
+        const body = { frequency, UTC_hour };
+        if (dayOfWeek !== undefined)
+            body.dayOfWeek = dayOfWeek;
+        return json(await api(`/v1/instances/${id}/backup-schedule`, {
+            method: "PUT",
+            body,
+        }));
+    });
+    server.tool("delete_backup", "Permanently delete a specific backup from an instance. Synchronous. Requires `instances:delete` scope on the API key. Does NOT affect the instance itself — only removes the backup's stored snapshot. Irreversible.", {
+        id: z.string().describe("The instance ID the backup belongs to"),
+        backupId: z.string().describe("The backup ID to delete"),
+    }, async ({ id, backupId }) => {
+        await api(`/v1/instances/${id}/backups/${backupId}`, {
+            method: "DELETE",
+        });
+        return json({ deleted: true, instanceId: id, backupId });
+    });
+    server.tool("clear_backup_schedule", "Remove the automated backup schedule from an instance (existing backups are kept). Synchronous; returns the updated instance.", { id: z.string().describe("The instance ID") }, async ({ id }) => json(await api(`/v1/instances/${id}/backup-schedule`, { method: "DELETE" })));
+}

package/dist/tools/billing.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBillingTools(server: McpServer): void;