ultipa-mcp 1.0.1

package/dist/tools/docs.js

@@ -0,0 +1,197 @@
+import { z } from "zod";
+// Topic slugs are full repo paths without the `.md` extension.
+// What's in this array is what's in the ultipa-docs repo, verbatim — no hidden
+// transformations. To add a new topic, copy the path from the repo and drop `.md`.
+const TOPICS = [
+    // gql / graph pattern matching
+    "gql/graph-pattern-matching/graph-pattern-matching",
+    "gql/graph-pattern-matching/node-and-edge-patterns",
+    "gql/graph-pattern-matching/graph-patterns",
+    "gql/graph-pattern-matching/path-patterns",
+    "gql/graph-pattern-matching/quantified-paths",
+    "gql/graph-pattern-matching/questioned-paths",
+    "gql/graph-pattern-matching/shortest-paths",
+    "gql/graph-pattern-matching/cheapest-paths",
+    "gql/graph-pattern-matching/khop-traversal",
+    // gql / graph management
+    "gql/graph-management/graphs",
+    "gql/graph-management/closed-graphs",
+    // gql / data manipulation
+    "gql/data-manipulation/node-and-edge-ids",
+    "gql/data-manipulation/insert",
+    "gql/data-manipulation/insert-overwrite",
+    "gql/data-manipulation/upsert",
+    "gql/data-manipulation/merge",
+    "gql/data-manipulation/foreach",
+    // gql / querying
+    "gql/querying/query-composition",
+    // gql / functions, operators, predicates, expressions
+    "gql/functions/all-functions",
+    "gql/operators",
+    "gql/predicates",
+    "gql/expressions",
+    // query perfermance
+    "gql/query-acceleration/index",
+    "gql/query-acceleration/fulltext-index",
+    "computing-engine/introduction",
+    // ontology (RDF / OWL semantics for ontology-mode graphs)
+    "ontology/introduction",
+    "ontology/class-definitions",
+    "ontology/object-properties",
+    "ontology/data-properties",
+    // graph-algorithms
+    "graph-algorithms/introduction",
+    "graph-algorithms/running-algorithms",
+    // stored-produceres
+    "stored-procedures/quick-start",
+    "stored-procedures/procedure-management",
+    "stored-procedures/calling-procedures",
+    "stored-procedures/procedure-body/procedure-body-language",
+];
+const REPO_BASE = "https://raw.githubusercontent.com/ultipa/ultipa-docs/main";
+const TREE_API_URL = "https://api.github.com/repos/ultipa/ultipa-docs/git/trees/main?recursive=1";
+// Reserved `topic` value that triggers a live fetch of the full doc page index
+// (from GitHub's tree API) instead of fetching a single markdown page.
+const INDEX_SLUG = "?";
+// Cache the index for the process lifetime — the tree rarely changes within a
+// session and unauth GitHub API has a 60 req/hour limit. On failure, clear so
+// the next call retries instead of returning a poisoned rejected promise.
+let cachedIndex = null;
+async function fetchRepoIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const promise = (async () => {
+        const res = await fetch(TREE_API_URL, {
+            headers: { Accept: "application/vnd.github+json" },
+        });
+        if (!res.ok) {
+            throw new Error(`GitHub tree API returned ${res.status} ${res.statusText}`);
+        }
+        const json = (await res.json());
+        return (json.tree ?? [])
+            .filter((n) => n.type === "blob" &&
+            typeof n.path === "string" &&
+            n.path.endsWith(".md") &&
+            n.path.includes("/"))
+            .map((n) => n.path.replace(/\.md$/, ""));
+    })();
+    cachedIndex = promise;
+    promise.catch(() => {
+        cachedIndex = null;
+    });
+    return promise;
+}
+// Convert a topic slug to its raw GitHub markdown URL — just append `.md`.
+function topicToFetchUrl(topic) {
+    return `${REPO_BASE}/${topic}.md`;
+}
+// Convert a topic slug to its rendered docs URL (for human fallback links).
+// `gql/graph-management/closed-graphs` → `https://www.ultipa.com/docs/gql/closed-graphs`
+// (ultipa.com flattens intermediate segments; only first segment + final page slug matter.)
+function topicToBrowseUrl(topic) {
+    const parts = topic.split("/");
+    const section = parts[0];
+    const page = parts[parts.length - 1];
+    return `https://www.ultipa.com/docs/${section}/${page}`;
+}
+function catalogResponse(prefix) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${prefix}\n\n${TOPICS.map((t) => `- ${t}`).join("\n")}`,
+            },
+        ],
+    };
+}
+// `lookup_docs` modes — single tool, three discovery layers, pay-as-you-go:
+//
+//   Call                                 Behavior
+//   -----------------------------------  ----------------------------------------------------------
+//   lookup_docs()                        Returns the curated TOPICS cheat-sheet. No network.
+//   lookup_docs({ topic: "?" })          Hits GitHub tree API, returns all .md paths in the
+//                                        repo (root README excluded). Cached for process
+//                                        lifetime; on failure the cache clears so the next
+//                                        call retries.
+//   lookup_docs({ topic: "some/path" })  Fetches that page's raw markdown from the repo.
+//   lookup_docs({ topic: "wrong/path" }) 404 from GitHub → handler returns error JSON with
+//                                        fetchedUrl, fallbackUrl, and curatedEntryPoints so the
+//                                        agent can self-correct in one round trip.
+//
+// No allowlist gate: any path is fetchable, validation is delegated to GitHub.
+export function registerDocsTools(server) {
+    server.tool("lookup_docs", `Look up an Ultipa documentation page by topic slug. Fetches the page's markdown content live from the public ultipa-docs repo on GitHub. Use this when you need authoritative reference on Ultipa-specific syntax, schema rules, functions, or features the model may not know fully from training data. Topic slugs are repo paths under https://github.com/ultipa/ultipa-docs without the \`.md\` extension; ANY valid path is fetchable, the list below is just curated entry points. Call WITHOUT a topic to see the cheat-sheet, or with \`topic: "?"\` to fetch the full live index of every doc page. Curated entry points: ${TOPICS.join(", ")}.`, {
+        topic: z
+            .string()
+            .optional()
+            .describe(`Any repo path under ultipa-docs without \`.md\` (e.g. \`${TOPICS[0]}\`). Pass \`?\` to fetch the full live index of every doc page from the repo. Omit to see the curated cheat-sheet of common entry points.`),
+    }, async ({ topic }) => {
+        if (!topic) {
+            return catalogResponse('No topic provided. Curated entry points below (you can also pass any other valid repo path, or `topic: "?"` to fetch the full live index from the repo):');
+        }
+        if (topic === INDEX_SLUG) {
+            try {
+                const all = await fetchRepoIndex();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Full index of ${all.length} doc pages in ultipa-docs (pass any of these as \`topic\` to fetch its markdown):\n\n${all.map((p) => `- ${p}`).join("\n")}`,
+                        },
+                    ],
+                };
+            }
+            catch (e) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "Failed to fetch repo index from GitHub. Fall back to the curated entry points below or pass a guessed slug directly.",
+                                detail: e?.message ?? String(e),
+                                curatedEntryPoints: TOPICS,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        const fetchedUrl = topicToFetchUrl(topic);
+        const fallbackUrl = topicToBrowseUrl(topic);
+        try {
+            const res = await fetch(fetchedUrl);
+            if (!res.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `Failed to fetch '${topic}' (${res.status} ${res.statusText}). Slug is likely wrong. **Next step**: call \`lookup_docs({ topic: "?" })\` to get the full live index of every doc page in the repo, locate the actual path for what you wanted, then re-call \`lookup_docs\` with the correct slug. Do NOT guess another slug blindly — the index is the authoritative list. As a fallback, the curated entry points below may also be close to what you need.`,
+                                fetchedUrl,
+                                fallbackUrl,
+                                nextStep: 'Call lookup_docs({ topic: "?" }) to fetch the full index.',
+                                curatedEntryPoints: TOPICS,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            return { content: [{ type: "text", text: await res.text() }] };
+        }
+        catch (e) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `Network error fetching '${topic}'.`,
+                            detail: e?.message ?? String(e),
+                            fetchedUrl,
+                            fallbackUrl,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/firewall.d.ts

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

package/dist/tools/firewall.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { api, json } from "../helpers/api.js";
+export function registerFirewallTools(server) {
+    server.tool("get_my_ip", "Return the public IP of the machine running this MCP server (as seen by Ultipa Cloud). Useful before `add_firewall_rule` — pass `${ip}/32` as the CIDR to allow just this machine. Note: with stdio transport (the current setup), the MCP server runs on the user's machine, so this is effectively the user's outbound IP. A future hosted MCP would return the hosting server's IP instead.", {}, async () => json(await api("/v1/instances/my-ip")));
+    server.tool("list_firewall_rules", "List the IP-allowlist (firewall) rules for an instance. Only applies to instances where `firewallSupported` is true (EC2-backed); free-trial / docker-host instances don't have firewalls.", { id: z.string().describe("The instance ID") }, async ({ id }) => json(await api(`/v1/instances/${id}/firewall-rules`)));
+    server.tool("add_firewall_rule", "Add a CIDR to the instance's IP allowlist. Use `0.0.0.0/0` to allow all (NOT recommended for production). Synchronous.", {
+        id: z.string().describe("The instance ID"),
+        cidr: z
+            .string()
+            .describe("CIDR block to allow, e.g. '203.0.113.42/32' for a single IP or '10.0.0.0/8' for a range"),
+        description: z
+            .string()
+            .optional()
+            .describe("Optional human-readable note for this rule"),
+    }, async ({ id, cidr, description }) => {
+        const body = { cidr };
+        if (description !== undefined)
+            body.description = description;
+        return json(await api(`/v1/instances/${id}/firewall-rules`, {
+            method: "POST",
+            body,
+        }));
+    });
+    server.tool("remove_firewall_rule", "Remove a firewall rule by its CIDR. The CIDR must match an existing rule exactly. Synchronous.", {
+        id: z.string().describe("The instance ID"),
+        cidr: z
+            .string()
+            .describe("CIDR of the rule to remove (must match an existing rule)"),
+    }, async ({ id, cidr }) => {
+        await api(`/v1/instances/${id}/firewall-rules`, {
+            method: "DELETE",
+            body: { cidr },
+        });
+        return json({ removed: true, id, cidr });
+    });
+}

package/dist/tools/instances.d.ts

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

package/dist/tools/instances.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import { api, json } from "../helpers/api.js";
+import { waitForSettled } from "../helpers/wait.js";
+import { makeProgressReporter } from "../helpers/progress.js";
+export function registerInstanceTools(server) {
+    // ── Read / discovery ────────────────────────────────────────────────────
+    server.tool("list_instances", "List all GQLDB instances on your Ultipa Cloud account.", {}, async () => json(await api("/v1/instances")));
+    server.tool("list_deleted_instances", "List instances that have been deleted from the account (kept as soft-deleted tombstones for audit / recovery). These do NOT appear in `list_instances`.", {}, async () => json(await api("/v1/instances/deleted")));
+    server.tool("get_instance", "Get details for a single instance by ID. Does NOT include the admin password — use get_instance_credentials for that.", { id: z.string().describe("The instance ID") }, async ({ id }) => json(await api(`/v1/instances/${id}`)));
+    server.tool("get_instance_credentials", "Fetch the admin DB credentials (adminUser + adminPassword) for an instance. Requires the API key to have the `instances:credentials` scope). The call is audit-logged server-side.", { id: z.string().describe("The instance ID") }, async ({ id }) => json(await api(`/v1/instances/${id}/credentials`)));
+    server.tool("list_regions", "List all regions Ultipa Cloud supports. Each entry has `value` (the region code used by `create_instance`, e.g. `us-east-1`), `label` (human-readable name), `provider` (e.g. `aws`), and `managerUrl` (the region's GQLDB Manager URL). Useful as a pre-step for `create_instance` or to give the user the right Manager URL for an instance.", {}, async () => json(await api("/v1/regions")));
+    server.tool("list_instance_sizes", "List available GQLDB instance sizes (CPU, memory, storage, pricing). Optionally filter by tier or region.", {
+        tier: z
+            .enum(["free_trial", "standard", "enterprise"])
+            .optional()
+            .describe("Filter by tier"),
+        region: z
+            .string()
+            .optional()
+            .describe("Filter by region code, e.g. us-east-1"),
+    }, async ({ tier, region }) => {
+        const q = new URLSearchParams();
+        if (tier)
+            q.set("tier", tier);
+        if (region)
+            q.set("region", region);
+        const qs = q.toString();
+        return json(await api(`/v1/instance-sizes${qs ? `?${qs}` : ""}`));
+    });
+    server.tool("get_enterprise_status", "Check the account's enterprise-tier eligibility. Returns `{ hasActiveEnterprise, canCreateEnterprise }`. Only meaningful for accounts whose email has enterprise sizes assigned. Pre-check before `create_instance` with an `enterprise` size.", {}, async () => json(await api("/v1/instances/enterprise-status")));
+    server.tool("get_operations_lock", "Check whether instance operations are currently locked (Ultipa Cloud maintenance). Returns `{ locked }`. When `locked: true`, all write/destructive ops (create, pause, resume, restart, delete, etc.) will be rejected upstream. Useful as a pre-check before chaining state-change tools — if locked, tell the user to wait rather than triggering ops that will fail.", {}, async () => json(await api("/v1/instances/operations-lock")));
+    server.tool("get_trial_status", "Check the account's free-trial eligibility. Returns `{ trialStartsAt, trialEndsAt, hasActiveTrial, canCreateTrial }`. Call before `create_instance` with a `free_trial` size — if `canCreateTrial` is false (trial expired or one already running), creating will fail.", {}, async () => json(await api("/v1/instances/trial-status")));
+    server.tool("get_latest_version", "Return the latest available GQLDB version. Pair with `get_instance` to compare against an instance's current `version` before calling `upgrade_version` — saves a 409 'already on latest' from the server when there's nothing to upgrade.", {}, async () => json(await api("/v1/gqldb-versions/latest")));
+    // ── State changes ───────────────────────────────────────────────────────
+    server.tool("create_instance", "Provision a new GQLDB instance. Blocks until the instance is fully provisioned and running (typically 30–60s). Returns the final instance object with `adminUser` and `adminPassword` merged in. **The `POST /v1/instances` response is the ONE place the password is surfaced** — subsequent GETs strip it — so surface the password to the user immediately on return. No follow-up `get_instance_credentials` call is needed.", {
+        name: z.string().min(1).max(30).describe("Instance name (1–30 chars)"),
+        region: z
+            .string()
+            .describe("Region code, e.g. us-east-1. Use list_instance_sizes to see valid regions."),
+        sizeId: z.string().describe("Size ID from list_instance_sizes"),
+    }, async ({ name, region, sizeId }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        await onProgress?.("Submitting create request...", undefined);
+        // POST /v1/instances is the only place adminPassword is surfaced — capture
+        // it now and merge into the final return after waitForSettled (which polls
+        // GET /v1/instances/:id, and GET strips the password).
+        const created = (await api("/v1/instances", {
+            method: "POST",
+            body: { name, region, sizeId },
+        }));
+        try {
+            const settled = await waitForSettled(created._id, "running", {
+                onProgress,
+            });
+            return json({ ...settled, adminPassword: created.adminPassword });
+        }
+        catch (e) {
+            throw new Error(`Instance ${created._id} WAS created but waiting for "running" failed: ${e?.message ?? e}. Do NOT call create_instance again — that would provision a duplicate. Initial adminPassword from the create response: "${created.adminPassword ?? "<not in response>"}" — surface it to the user before retrying anything. Call wait_for_instance_status(id="${created._id}") to keep waiting, or get_instance(id="${created._id}") to check the current state.`);
+        }
+    });
+    server.tool("rename_instance", "Rename an instance (display name only — does not affect host, port, credentials, or any client connections). Synchronous: returns the updated instance immediately.", {
+        id: z.string().describe("The instance ID"),
+        name: z.string().min(1).max(30).describe("New name (1–30 chars)"),
+    }, async ({ id, name }) => json(await api(`/v1/instances/${id}`, {
+        method: "PATCH",
+        body: { name },
+    })));
+    server.tool("pause_instance", "Pause a running GQLDB instance. Blocks until the pause completes and the instance has fully settled in 'paused' (typically ~60s). Stops compute billing while paused (storage still billed).", { id: z.string().describe("The instance ID") }, async ({ id }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        await api(`/v1/instances/${id}/pause`, { method: "POST" });
+        return json(await waitForSettled(id, "paused", { onProgress }));
+    });
+    server.tool("resume_instance", "Resume a paused GQLDB instance. Blocks until the resume completes and the instance is fully 'running' (typically 60–120s). Note: during resume, `status` stays 'paused' the whole time and only `progressStep` changes — that's expected.", { id: z.string().describe("The instance ID") }, async ({ id }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        await api(`/v1/instances/${id}/resume`, { method: "POST" });
+        return json(await waitForSettled(id, "running", { onProgress }));
+    });
+    server.tool("restart_instance", "Restart a GQLDB instance. Blocks until the restart completes and the instance is back to 'running' (typically ~60s). Note: `status` stays 'running' for the whole restart — only `progressStep` changes.", { id: z.string().describe("The instance ID") }, async ({ id }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        await api(`/v1/instances/${id}/restart`, { method: "POST" });
+        return json(await waitForSettled(id, "running", { onProgress }));
+    });
+    server.tool("upgrade_version", "Upgrade a GQLDB instance to the latest available version. Blocks until the upgrade completes and the instance is back to 'running' (can take several minutes; default timeout 5 min). Errors out with 409 if already on the latest version — call `get_latest_version` first and compare against the instance's current `version` if you want to avoid that.", { id: z.string().describe("The instance ID") }, async ({ id }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        await api(`/v1/instances/${id}/upgrade`, { method: "POST" });
+        return json(await waitForSettled(id, "running", {
+            onProgress,
+            timeoutMs: 300_000,
+        }));
+    });
+    server.tool("delete_instance", "Delete an instance. Blocks until deletion fully completes upstream (status reaches 'deleted' or the instance is gone — typically 30–60s). Requires the instance name as a confirmation arg — must exactly match the current instance name, or the call is rejected without contacting the server.", {
+        id: z.string().describe("The instance ID"),
+        confirmName: z
+            .string()
+            .describe("Must exactly match the target instance's current name"),
+    }, async ({ id, confirmName }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        const inst = (await api(`/v1/instances/${id}`));
+        if (inst?.name !== confirmName) {
+            throw new Error(`confirmName mismatch: instance ${id} is named "${inst?.name}", but confirmName was "${confirmName}". Refusing to delete.`);
+        }
+        await api(`/v1/instances/${id}`, { method: "DELETE" });
+        await waitForSettled(id, "deleted", { onProgress });
+        return json({ deleted: true, id, name: confirmName });
+    });
+    server.tool("reset_admin_password", "Rotate the admin DB password for an instance and return the new value. Uses the `instances:write` scope. WARNING: any existing apps / drivers / sessions using the old password will be broken until reconfigured. Only call this when the user explicitly asks to reset/rotate the password — do not call it as an automatic fallback for `get_instance_credentials`.", {
+        id: z.string().describe("The instance ID"),
+        password: z
+            .string()
+            .min(6)
+            .max(128)
+            .optional()
+            .describe("Optional new password (6–128 chars). If omitted, the server generates one."),
+    }, async ({ id, password }) => json(await api(`/v1/instances/${id}/reset-password`, {
+        method: "POST",
+        body: password === undefined ? {} : { password },
+    })));
+    server.tool("set_log_level", "Set the GQLDB log level on an instance. Blocks until the change is applied (typically a few seconds). `status` stays 'running' throughout; only `progressStep` changes.", {
+        id: z.string().describe("The instance ID"),
+        level: z
+            .enum(["debug", "info", "warn", "error"])
+            .describe("New log level"),
+    }, async ({ id, level }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        await api(`/v1/instances/${id}/log-level`, {
+            method: "POST",
+            body: { level },
+        });
+        return json(await waitForSettled(id, "running", { onProgress }));
+    });
+    // ── Recovery / explicit polling (rarely needed directly) ────────────────
+    server.tool("wait_for_instance_status", "Block until an instance settles into the target status (default 'running'). NOTE: you usually do NOT need to call this directly — `create_instance`, `pause_instance`, `resume_instance`, `restart_instance`, `upgrade_version`, `set_log_level`, and `delete_instance` all auto-wait internally. Use this only for explicit/manual polling (e.g. recovering from a half-known state, or waiting on an instance someone else triggered). An instance is 'in transition' whenever `progressStep` is non-empty OR `status` is one of `provisioning`/`upgrading`/`deleting`. Throws on `error` / `suspended` / `deleted`, on settling on any other non-target status, or on timeout.", {
+        id: z.string().describe("The instance ID"),
+        target: z
+            .enum(["running", "paused"])
+            .default("running")
+            .describe("Target status. Default 'running'. Use 'paused' after pause_instance."),
+        timeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .default(180_000)
+            .describe("Max time to wait, in milliseconds. Default 180000 (3 min). Resume / restart of larger instances can take 60–120s."),
+        pollIntervalMs: z
+            .number()
+            .int()
+            .positive()
+            .default(3000)
+            .describe("Polling interval, in milliseconds. Default 3000."),
+    }, async ({ id, target, timeoutMs, pollIntervalMs }, extra) => {
+        const onProgress = makeProgressReporter(extra);
+        return json(await waitForSettled(id, target, {
+            timeoutMs,
+            pollIntervalMs,
+            onProgress,
+        }));
+    });
+}

package/dist/tools/logs.d.ts

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

package/dist/tools/logs.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { api, json } from "../helpers/api.js";
+export function registerLogTools(server) {
+    server.tool("get_instance_logs", "Fetch recent container logs from a GQLDB instance. Default 100 lines, max 1000.", {
+        id: z.string().describe("The instance ID"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(1000)
+            .default(100)
+            .describe("Max number of log lines to return (1–1000). Default 100."),
+    }, async ({ id, limit }) => json(await api(`/v1/instances/${id}/logs?limit=${limit}`)));
+}

package/dist/tools/metrics.d.ts

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

package/dist/tools/metrics.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { api, json } from "../helpers/api.js";
+export function registerMetricsTools(server) {
+    server.tool("get_live_metrics", "Current snapshot of an instance's metrics (CPU, memory, disk, network). Single point-in-time reading; use `get_metrics_history` for a time series.", { id: z.string().describe("The instance ID") }, async ({ id }) => json(await api(`/v1/instances/${id}/metrics`)));
+    server.tool("get_metrics_history", "Historical metrics for an instance over the last N minutes. Default 60, max 20160 (14 days).", {
+        id: z.string().describe("The instance ID"),
+        range: z
+            .number()
+            .int()
+            .min(1)
+            .max(20160)
+            .default(60)
+            .describe("Lookback window in minutes (1–20160). Default 60."),
+    }, async ({ id, range }) => json(await api(`/v1/instances/${id}/metrics/history?range=${range}`)));
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "ultipa-mcp",
+  "version": "1.0.1",
+  "description": "Model Context Protocol server for Ultipa Cloud and any self-managed Ultipa GQLDB instance. Operate instances, run GQL, manage backups from any MCP client (Claude Desktop, Cursor, etc.).",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ultipa-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ultipa",
+    "gqldb",
+    "graph-database",
+    "gql",
+    "claude",
+    "cursor"
+  ],
+  "author": "Ultipa",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ultipa/ultipa-mcp.git"
+  },
+  "homepage": "https://github.com/ultipa/ultipa-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/ultipa/ultipa-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@ultipa-graph/ultipa-driver": "^6.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "prettier": "^3.4.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.6.3"
+  }
+}