ultipa-mcp 1.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Ultipa
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# Ultipa MCP
+
+Model Context Protocol server for [Ultipa Cloud](https://dbaas.ultipa.com) and any self-managed Ultipa GQLDB instance. Lets MCP clients provision and operate instances, run GQL queries, manage backups, view metrics, and more, all through natural language.
+
+## Auth
+
+Each MCP server entry in your client's config points at one Ultipa target via one of two paths:
+
+| Path | Use it if | Env vars |
+|---|---|---|
+| **Ultipa Cloud** | You manage instances via [Ultipa Cloud](https://dbaas.ultipa.com). | `ULTIPA_CLOUD_API_KEY` (create at [Ultipa Cloud](https://dbaas.ultipa.com) → Settings → API Keys) |
+| **Direct instance** | You have admin credentials to a single GQLDB instance. | `ULTIPA_HOST` + `ULTIPA_USERNAME` + `ULTIPA_PASSWORD`, optional `ULTIPA_GRAPH` |
+
+Need both, or multiple direct instances? Add more entries (see [Multiple targets](#multiple-targets)).
+
+**Ultipa Cloud API key permissions** depend on which tools you'll use:
+
+| Permission | What it unlocks |
+|---|---|
+| `instances:read` | All read tools (list, get, metrics, …) |
+| `instances:write` | State changes (create, pause, restart, upgrade, set log level, schedule backups, …) |
+| `instances:delete` | `delete_instance`, `delete_backup` |
+| `instances:credentials` | `get_instance_credentials`. Also required by the data-plane tools under Ultipa Cloud account mode, because they fetch credentials per call. |
+| `billing:read`, `billing:write` | The billing tools |
+
+## Install
+
+### One target via install-mcp
+
+Replace `claude` with your client: `cursor`, `windsurf`, `vscode`, `cline`, etc.
+
+For an Ultipa Cloud account:
+
+```bash
+npx -y install-mcp@latest ultipa-mcp --client claude \
+  --env ULTIPA_CLOUD_API_KEY=uc_...
+```
+
+For a direct instance:
+
+```bash
+npx -y install-mcp@latest ultipa-mcp --client claude \
+  --env ULTIPA_HOST=<host>:<port> \
+  --env ULTIPA_USERNAME=admin \
+  --env ULTIPA_PASSWORD=<password> \
+  --env ULTIPA_GRAPH=default
+```
+
+### Multiple targets
+
+Each MCP server entry in your client's config points at one Ultipa target. Add as many entries as you need, with descriptive names. Claude (or any agent) sees each entry as its own toolset and picks based on what you ask (e.g. "query staging" routes to the `ultipa-staging` entry).
+
+The same JSON shape works in any stdio MCP client; only the file path differs (Claude Desktop: `claude_desktop_config.json` via Settings → Developer → Edit Config; Cursor: `~/.cursor/mcp.json`; Windsurf, VS Code MCP extensions: see their docs).
+
+```json
+{
+  "mcpServers": {
+    "ultipa-cloud": {
+      "command": "npx",
+      "args": ["-y", "ultipa-mcp"],
+      "env": {
+        "ULTIPA_CLOUD_API_KEY": "uc_..."
+      }
+    },
+    "ultipa-staging": {
+      "command": "npx",
+      "args": ["-y", "ultipa-mcp"],
+      "env": {
+        "ULTIPA_HOST": "staging.internal:60061",
+        "ULTIPA_USERNAME": "admin",
+        "ULTIPA_PASSWORD": "..."
+      }
+    },
+    "ultipa-prod": {
+      "command": "npx",
+      "args": ["-y", "ultipa-mcp"],
+      "env": {
+        "ULTIPA_HOST": "prod.internal:60061",
+        "ULTIPA_USERNAME": "admin",
+        "ULTIPA_PASSWORD": "..."
+      }
+    }
+  }
+}
+```
+
+Restart your client after editing.
+
+## Tools
+
+### Account
+
+Requires Ultipa Cloud (`ULTIPA_CLOUD_API_KEY`).
+
+| Tool | What it does |
+|---|---|
+| `get_account` | Authenticated account profile (email, name, balance flags). |
+
+### Instance lifecycle
+
+Requires Ultipa Cloud (`ULTIPA_CLOUD_API_KEY`).
+
+| Tool | What it does |
+|---|---|
+| `list_instances` | List all instances on the account. |
+| `get_instance` | Fetch one instance by ID. |
+| `list_deleted_instances` | List deleted instances (not returned by `list_instances`). |
+| `create_instance` | Provision a new instance (name, region, sizeId). |
+| `rename_instance` | Change an instance's display name. |
+| `pause_instance` | Pause a running instance. |
+| `resume_instance` | Resume a paused instance. |
+| `restart_instance` | Restart the instance. |
+| `upgrade_version` | Upgrade to the latest GQLDB version. |
+| `delete_instance` | Delete an instance. Requires the instance name as confirmation. |
+| `get_instance_credentials` | Fetch admin username and password of the instance. |
+| `reset_admin_password` | Rotate the admin DB password. Breaks existing connections. |
+| `list_regions` | List supported regions and their Manager URLs. |
+| `list_instance_sizes` | List available sizes and pricing. |
+| `get_latest_version` | Latest available GQLDB version. |
+| `get_trial_status` | Free-trial eligibility. Pre-check before creating a free-trial instance. |
+| `get_enterprise_status` | Enterprise-tier eligibility. Pre-check before creating an enterprise instance. |
+| `get_operations_lock` | Whether instance ops are globally locked (maintenance / freeze). |
+| `wait_for_instance_status` | Explicit polling helper. Rarely needed. |
+
+### Metrics, Logs & Alerts
+
+Requires Ultipa Cloud (`ULTIPA_CLOUD_API_KEY`).
+
+| Tool | What it does |
+|---|---|
+| `get_live_metrics` | Current CPU / memory / disk / network snapshot. |
+| `get_metrics_history` | Historical metrics over the last N minutes (default 60, max 14 days). |
+| `get_instance_logs` | Recent container logs (default 100 lines, max 1000). |
+| `set_log_level` | Set GQLDB log level (debug / info / warn / error). |
+| `list_alerts` | All alerts across the account's instances. |
+| `list_instance_alerts` | Alerts for a single instance. |
+
+### Firewall
+
+Requires Ultipa Cloud (`ULTIPA_CLOUD_API_KEY`).
+
+| Tool | What it does |
+|---|---|
+| `get_my_ip` | Public IP of the machine running Ultipa MCP (pair with `add_firewall_rule` to allow `${ip}/32`). |
+| `list_firewall_rules` | IP-allowlist rules for an instance. |
+| `add_firewall_rule` | Add a CIDR to the allowlist. |
+| `remove_firewall_rule` | Remove a rule by its CIDR. |
+
+### Backups
+
+Requires Ultipa Cloud (`ULTIPA_CLOUD_API_KEY`).
+
+| Tool | What it does |
+|---|---|
+| `list_backups` | List backups for an instance. |
+| `create_backup` | Trigger an on-demand backup (default 10-min timeout). |
+| `restore_backup` | Restore from a completed backup. **Destructive: overwrites current data.** |
+| `delete_backup` | Permanently delete a backup snapshot. |
+| `set_backup_schedule` | Set/update an automated backup schedule. |
+| `clear_backup_schedule` | Remove the schedule (existing backups kept). |
+
+### Billing
+
+Requires Ultipa Cloud (`ULTIPA_CLOUD_API_KEY`).
+
+| Tool | What it does |
+|---|---|
+| `get_balance` | Current account balance and billing flags. |
+| `list_transactions` | Balance transactions (top-ups, charges, refunds). |
+| `get_usage` | Monthly usage-based billing summary. |
+| `get_payment_method` | Saved card info. |
+| `get_auto_reload` | Current auto-reload settings. |
+| `set_auto_reload` | Update auto-reload settings. |
+| `topup_balance` | Top up balance with a saved card. |
+| `start_payment_method_setup` | Stripe Checkout URL for adding/changing the saved card. |
+
+### Data plane
+
+Works with either Ultipa Cloud or a Direct instance.
+
+| Tool | What it does |
+|---|---|
+| `test_connection` | Quick health check on the target GQLDB instance. |
+| `run_gql_query` | Execute a GQL query and return results. |
+| `explain_query` | Return the execution plan without running the query. |
+| `run_algo` | Run a built-in graph algorithm. Centrality, community detection, similarity, pathfinding, graph embeddings, etc. Same execution as `run_gql_query`; separate so the agent surfaces the algorithm catalog for analytical questions. |
+| `list_graphs` | List all graphs on the instance. |
+| `describe_schema` | Detect graph mode (OPEN / CLOSED / ONTOLOGY) and run schema introspection. |
+| `create_graph` | Create a new graph (OPEN / CLOSED / ONTOLOGY). |
+| `delete_graph` | Drop a graph. |
+| `write_data` | Run a GQL DML statement the agent composes by hand. For files on the user's machine, use `import_data` instead. |
+| `import_data` | Bulk-write structured nodes / edges via the driver's gRPC bulk-insert path. Highly recommend to provide filepath to the CSV, JSON, or JSONL files. |
+| `write_procedure` | Create a stored procedure. |
+| `get_db_version` | Live GQLDB version reported by the instance. |
+| `get_db_license` | GQLDB Edition + license info. |
+| `reload_db_stats` | Rebuild the instance's stored statistics. |
+
+### Docs
+
+Works with either Ultipa Cloud or a Direct instance.
+
+| Tool | What it does |
+|---|---|
+| `lookup_docs` | Fetch Ultipa documentation pages by topic. Useful for the agent to ground GQLDB features and GQL composition in authoritative reference. |
+
+## Troubleshooting
+
+| Symptom | Likely cause / fix |
+|---|---|
+| `ENOENT: no such file or directory` from `import_data` with `filePath` | The path is on your agent's sandbox, not the MCP host. Drag the file into your terminal to copy its real host path, or paste the file content via `csv` mode. |
+| Edge insert rejected with "EDGE_ID disabled" or custom `_id` not allowed | The graph has edge `_id` disabled. Run `ALTER GRAPH <name> SET EDGE_ID ENABLED` via `run_gql_query`, or drop the `_id` from your edge data. |
+| `instances:credentials` permission required (data plane fails on a Cloud target) | Your `ULTIPA_CLOUD_API_KEY` doesn't have `instances:credentials`. Regenerate the key with that scope at https://dbaas.ultipa.com → Settings → API Keys. |
+| `list_instances` shows nothing even though you have an instance | You're targeting a Direct instance (env vars only), not a Cloud account. `list_instances` only sees Cloud instances. Call `test_connection` (omit `id`) to confirm the Direct instance is reachable. |
+| `create_instance` succeeded but `adminPassword` is missing in the response | The Cloud REST `POST /v1/instances` returns the password exactly once. If you missed it, call `get_instance_credentials` (requires the `instances:credentials` scope). |
+| MCP launches but exits immediately with "needs at least one auth mode" | None of `ULTIPA_CLOUD_API_KEY` or the Direct trio (`ULTIPA_HOST` + `ULTIPA_USERNAME` + `ULTIPA_PASSWORD`) are set. Add them to your MCP client's `env` block. |
+| MCP launches but exits with "Direct instance config is incomplete" | You set one or two of the Direct env vars; all three (`ULTIPA_HOST`, `ULTIPA_USERNAME`, `ULTIPA_PASSWORD`) are required together. |
+| `import_data` very slow / truncated in `csv` or arrays mode | The agent's output rate is the bottleneck. Provide a host file path so the MCP uses `filePath` mode (constant tokens), or fall back to Ultipa Manager → Data Integration for very large imports. |
+
+For agent-side trace debugging, set `ULTIPA_MCP_DEBUG=1` in the MCP env to log every tool call name + latency to stderr.
+
+## License
+
+ISC

package/dist/helpers/api.d.ts

@@ -0,0 +1,9 @@
+export declare function api(path: string, init?: Omit<RequestInit, "body"> & {
+    body?: unknown;
+}): Promise<any>;
+export declare const json: (data: unknown) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/helpers/api.js

@@ -0,0 +1,25 @@
+import { API_KEY, BASE_URL } from "./env.js";
+export async function api(path, init = {}) {
+    if (!API_KEY) {
+        throw new Error("This tool needs Ultipa Cloud (ULTIPA_CLOUD_API_KEY) but only a Direct instance is configured.");
+    }
+    const { body, ...rest } = init;
+    const res = await fetch(`${BASE_URL}${path}`, {
+        ...rest,
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": API_KEY,
+            ...(rest.headers ?? {}),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!res.ok) {
+        throw new Error(`${res.status} ${res.statusText}: ${await res.text()}`);
+    }
+    if (res.status === 204)
+        return null;
+    return res.json();
+}
+export const json = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});

package/dist/helpers/dataplane.d.ts

@@ -0,0 +1,5 @@
+import { GqldbClient } from "@ultipa-graph/ultipa-driver";
+export declare function getDataPlaneClient(target: string): Promise<GqldbClient>;
+export declare function resolveDataPlaneTarget(id: string | undefined): string;
+export declare function serializeResponse(r: any): any;
+export declare function closeAllDataPlaneClients(): Promise<void>;

package/dist/helpers/dataplane.js

@@ -0,0 +1,88 @@
+import { GqldbClient, ConfigBuilder } from "@ultipa-graph/ultipa-driver";
+import { api } from "./api.js";
+import { INSTANCE_HOST, INSTANCE_USER, INSTANCE_PASSWORD, hasModeA, hasModeB, } from "./env.js";
+// Data-plane client cache. Keys: "direct" (env-configured single instance) or an instance ID
+// (resolved via Ultipa Cloud). Values are lazily-opened, logged-in GqldbClient promises.
+const clientCache = new Map();
+async function buildDataPlaneClient(target) {
+    let host;
+    let user;
+    let password;
+    if (target === "direct") {
+        host = INSTANCE_HOST;
+        user = INSTANCE_USER;
+        password = INSTANCE_PASSWORD;
+    }
+    else {
+        // Ultipa Cloud: target is an instance ID. Resolve host + credentials via the Cloud control plane.
+        const inst = (await api(`/v1/instances/${target}`));
+        if (inst.status !== "running") {
+            throw new Error(`Instance ${target} is not running (status: "${inst.status}"). Data-plane calls require a running instance.`);
+        }
+        if (!inst.host || !inst.port) {
+            throw new Error(`Instance ${target} has no reachable host/port (host="${inst.host}", port=${inst.port}).`);
+        }
+        const creds = (await api(`/v1/instances/${target}/credentials`));
+        host = `${inst.host}:${inst.port}`;
+        user = creds.adminUser;
+        password = creds.adminPassword;
+    }
+    const cfg = new ConfigBuilder()
+        .hosts(host)
+        .username(user)
+        .password(password)
+        .timeoutSeconds(120)
+        .build();
+    const client = new GqldbClient(cfg);
+    try {
+        await client.login(user, password);
+    }
+    catch (e) {
+        // Don't leak an un-logged-in client — gRPC channel + driver state.
+        await client.close().catch(() => { });
+        throw e;
+    }
+    return client;
+}
+export async function getDataPlaneClient(target) {
+    let pending = clientCache.get(target);
+    if (!pending) {
+        pending = buildDataPlaneClient(target);
+        clientCache.set(target, pending);
+        // On failure, drop the cache entry so the next call retries with a fresh build.
+        pending.catch(() => clientCache.delete(target));
+    }
+    return pending;
+}
+export function resolveDataPlaneTarget(id) {
+    if (id) {
+        if (!hasModeA) {
+            throw new Error("This call passed an `id`, which routes through Ultipa Cloud, but ULTIPA_CLOUD_API_KEY is not configured. Either set it, or omit `id` to use the Direct instance.");
+        }
+        return id;
+    }
+    if (!hasModeB) {
+        throw new Error("No `id` provided and Direct instance (ULTIPA_HOST + ULTIPA_USERNAME + ULTIPA_PASSWORD) is not configured. Pass `id` to target an instance via Ultipa Cloud, or set the Direct instance env vars to designate a default.");
+    }
+    return "direct";
+}
+export function serializeResponse(r) {
+    // Convert the driver's Response into a clean JSON shape: column names, rows as objects
+    // keyed by column name, plus row count. `toJSON()` on the SDK is typed as `string`, so
+    // calling it would force the agent to parse a string out of the tool result — instead we
+    // use `toObjects()` to project rows into a plain object array.
+    if (r && typeof r === "object" && typeof r.toObjects === "function") {
+        return {
+            columns: r.columns,
+            rows: r.toObjects(),
+            rowCount: r.rowCount,
+            rowsAffected: r.rowsAffected,
+        };
+    }
+    return r;
+}
+export async function closeAllDataPlaneClients() {
+    const pending = [...clientCache.values()];
+    clientCache.clear();
+    await Promise.allSettled(pending.map((p) => p.then((c) => c.close()).catch(() => { })));
+}

package/dist/helpers/env.d.ts

@@ -0,0 +1,9 @@
+export declare const API_KEY: string | undefined;
+export declare const BASE_URL: string;
+export declare const INSTANCE_HOST: string | undefined;
+export declare const INSTANCE_USER: string | undefined;
+export declare const INSTANCE_PASSWORD: string | undefined;
+export declare const DEFAULT_GRAPH: string | undefined;
+export declare const hasModeA: boolean;
+export declare const hasModeB: boolean;
+export declare const DEBUG: boolean;

package/dist/helpers/env.js

@@ -0,0 +1,19 @@
+// Centralized env-var reading + auth-mode flags.
+// Both modes are independent; either or both can be configured.
+// Ultipa Cloud — control plane + data-plane access against any account instance via `id`
+export const API_KEY = process.env.ULTIPA_CLOUD_API_KEY;
+export const BASE_URL = process.env.ULTIPA_CLOUD_BASE_URL ?? "https://dbaas.ultipa.com";
+// Direct instance — data plane only, against the env-configured GQLDB instance
+export const INSTANCE_HOST = process.env.ULTIPA_HOST;
+export const INSTANCE_USER = process.env.ULTIPA_USERNAME;
+export const INSTANCE_PASSWORD = process.env.ULTIPA_PASSWORD;
+export const DEFAULT_GRAPH = process.env.ULTIPA_GRAPH;
+export const hasModeA = !!API_KEY;
+export const hasModeB = !!(INSTANCE_HOST && INSTANCE_USER && INSTANCE_PASSWORD);
+// Debug logging — when ULTIPA_MCP_DEBUG is truthy ("1", "true", etc.), every
+// tool call's name + latency + error (if any) goes to stderr. Useful for
+// agent-trace debugging without slowing down normal operation.
+export const DEBUG = (() => {
+    const v = process.env.ULTIPA_MCP_DEBUG?.toLowerCase().trim();
+    return v === "1" || v === "true" || v === "yes" || v === "on";
+})();

package/dist/helpers/import.d.ts

@@ -0,0 +1,45 @@
+import type { EdgeData, NodeData } from "@ultipa-graph/ultipa-driver";
+export declare function parseCsv(text: string, opts?: {
+    delimiter?: string;
+    quote?: string;
+}): string[][];
+export declare function coerceCell(value: string, type?: string): any;
+export declare function csvToCanonical(content: string, opts: {
+    label: string;
+    idColumn?: string;
+    fromColumn?: string;
+    toColumn?: string;
+    properties?: Array<{
+        property: string;
+        column: string;
+        type?: string;
+    }>;
+    delimiter?: string;
+    quote?: string;
+}): {
+    nodes?: NodeData[];
+    edges?: EdgeData[];
+    rowCount: number;
+};
+export declare function jsonToCanonical(content: string, isJsonl: boolean): {
+    nodes?: NodeData[];
+    edges?: EdgeData[];
+};
+export declare function loadFilePath(path: string, csvOpts: {
+    label?: string;
+    idColumn?: string;
+    fromColumn?: string;
+    toColumn?: string;
+    properties?: Array<{
+        property: string;
+        column: string;
+        type?: string;
+    }>;
+    delimiter?: string;
+    quote?: string;
+}): Promise<{
+    nodes?: NodeData[];
+    edges?: EdgeData[];
+    format: "csv" | "json" | "jsonl";
+    rowCount?: number;
+}>;