hydrilla-mcp 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# Hydrilla MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Stdio MCP server for the Hydrilla developer API. Shared across Cursor, Claude Code, and other MCP clients via project-root `.mcp.json` (not under `.cursor/`).
+
+## Build
+
+```bash
+cd apps/frontend/plugins/mcp
+pnpm install   # or npm install
+pnpm run build # or npm run build
+```
+
+## Secrets
+
+```bash
+cp mcp.env.example mcp.env
+# edit mcp.env — never commit mcp.env
+```
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `HYDRILLA_API_KEY` | No, if a plugin has the key | `hyd_live_…` from `/app/api-keys`. When unset, the server uses the key pasted into a Hydrilla plugin (`~/.hydrilla/config.json`), read on every call |
+| `HYDRILLA_API_BASE` | No | Defaults to production backend |
+| `POSTHOG_PROJECT_TOKEN` | Recommended | `phc_…` for MCP Analytics |
+| `POSTHOG_HOST` | No | Defaults to `https://us.i.posthog.com` |
+
+## Project MCP config (any AI)
+
+Committed configs (no secrets):
+
+- Workspace root: `Hydrilla_all/.mcp.json`
+- Repo root: `hydrilla-ai/.mcp.json`
+
+Both point at `dist/index.js` with a path relative to that folder. The server loads `mcp.env` from its own directory. Do not use `${workspaceFolder}` or `envFile` here: Claude Code does not expand that variable and does not read `envFile`.
+
+Public install (same flow as the MCP page). The npm package is `hydrilla-mcp` (Node.js 20+). Replace `hyd_live_…` with a key from `/app/api-keys`. The key stays in the client config, not in chat.
+
+Claude Code (macOS / Linux):
+
+```bash
+claude mcp add -s user hydrilla --env HYDRILLA_API_KEY=hyd_live_… -- npx -y hydrilla-mcp
+```
+
+Claude Code (Windows):
+
+```bash
+claude mcp add -s user hydrilla --env HYDRILLA_API_KEY=hyd_live_… "--" cmd /c npx -y hydrilla-mcp
+```
+
+Codex:
+
+```bash
+codex mcp add hydrilla --env HYDRILLA_API_KEY=hyd_live_… -- npx -y hydrilla-mcp
+```
+
+Cursor: open the install link from `/integrations/mcp`, or paste this into `~/.cursor/mcp.json` and turn `hydrilla` on:
+
+```json
+{
+  "mcpServers": {
+    "hydrilla": {
+      "command": "npx",
+      "args": ["-y", "hydrilla-mcp"],
+      "env": {
+        "HYDRILLA_API_KEY": "hyd_live_…"
+      }
+    }
+  }
+}
+```
+
+Local checkout of this repo:
+
+```json
+{
+  "mcpServers": {
+    "hydrilla": {
+      "command": "node",
+      "args": ["apps/frontend/plugins/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+The path is relative to the folder that contains `.mcp.json`. The server reads `mcp.env` beside itself, so the key is not written into this file.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `hydrilla_me` | Plan and credit balance. Free. |
+| `hydrilla_text_to_3d` | Generate a GLB from a prompt. `send_to` places it in an open app. |
+| `hydrilla_image_to_3d` | Generate a GLB from an image URL. `send_to` places it in an open app. |
+| `hydrilla_get_task` | Status and mesh URL of one task. |
+| `hydrilla_list_tasks` | Recent models on the account. Free. |
+| `hydrilla_cancel_task` | Stop a running task; unused credits are refunded. |
+| `hydrilla_list_apps` | Which apps have their Bridge running right now. |
+| `hydrilla_send_to_app` | Put an existing model into Blender, Unity, Unreal, Godot, Maya or 3ds Max. Free. |
+
+## Sending models into an app
+
+Each Hydrilla plugin has a **Run Bridge** button that listens on its own local port
+(Blender 7345, Maya 7346, 3ds Max 7347, Unreal 7348, Unity 7349, Godot 7350). With the
+Bridge running, `send_to: "blender"` on a generate tool, or `hydrilla_send_to_app`, makes
+the plugin download the GLB and import it into the open scene. If the Bridge is off, the
+tool says which button to click and the model can be sent again without regenerating.
+
+A generate call waits up to 8 minutes and reports progress to clients that ask for it. If
+the model is not ready by then, it returns the task id to check with `hydrilla_get_task`.

package/dist/api.js

@@ -0,0 +1,131 @@
+import { API_KEYS_URL, SERVER_VERSION, resolveApiBase, resolveApiKey } from "./config.js";
+const REQUEST_TIMEOUT_MS = 60_000;
+/** Text-to-3D creates its concept image before the request returns. */
+export const CREATE_TIMEOUT_MS = 240_000;
+const POLL_INTERVAL_MS = 2_000;
+const MAX_POLL_FAILURES = 5;
+const NO_KEY_MESSAGE = `No Hydrilla API key found. Ask the user to add their key in the Hydrilla plugin (for example the Hydrilla tab in Blender), ` +
+    `or to set HYDRILLA_API_KEY in this MCP server's config. Keys are created at ${API_KEYS_URL}. ` +
+    `Do not ask the user to paste the key into the chat.`;
+const BAD_KEY_MESSAGE = `Hydrilla did not accept the API key. Ask the user to check it or create a new one at ${API_KEYS_URL}, ` +
+    `then update it in the Hydrilla plugin or this MCP server's config. Do not ask for the key in the chat.`;
+export class HydrillaError extends Error {
+    status;
+    constructor(message, status = 0) {
+        super(message);
+        this.name = "HydrillaError";
+        this.status = status;
+    }
+}
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+function isTerminal(status) {
+    return status === "SUCCEEDED" || status === "FAILED" || status === "CANCELLED";
+}
+function messageFor(status, data) {
+    if (status === 401) {
+        return BAD_KEY_MESSAGE;
+    }
+    const body = (data ?? {});
+    const nested = typeof body.error === "object" ? body.error?.message : body.error;
+    const fromBody = nested || body.message;
+    if (fromBody) {
+        return String(fromBody);
+    }
+    if (status === 402) {
+        return "Not enough Hydrilla credits. The user can top up at hydrilla.ai.";
+    }
+    if (status === 429) {
+        return "Too many requests to Hydrilla. Wait a moment and try again.";
+    }
+    if (status >= 500) {
+        return `Hydrilla is having trouble right now (${status}). Try again shortly.`;
+    }
+    return `Hydrilla API request failed (${status}).`;
+}
+const fetchResponse = async (url, init, timeoutMs) => {
+    try {
+        return await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new HydrillaError(`Could not reach the Hydrilla API at ${new URL(url).host}: ${reason}`);
+    }
+};
+const parseJson = async (response) => {
+    const text = await response.text();
+    if (!text) {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // A gateway error page or other non-JSON body; the status code carries the meaning.
+        return {};
+    }
+};
+export async function api(path, init = {}, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const apiKey = resolveApiKey();
+    if (!apiKey) {
+        throw new HydrillaError(NO_KEY_MESSAGE, 401);
+    }
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${apiKey}`);
+    headers.set("Accept", "application/json");
+    headers.set("User-Agent", `Hydrilla-MCP/${SERVER_VERSION}`);
+    if (init.body && !headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+    }
+    const response = await fetchResponse(`${resolveApiBase()}${path}`, { ...init, headers }, timeoutMs);
+    const data = await parseJson(response);
+    if (!response.ok) {
+        throw new HydrillaError(messageFor(response.status, data), response.status);
+    }
+    return data;
+}
+export const getTask = (taskId) => api(`/v1/3d/tasks/${encodeURIComponent(taskId)}`);
+const pollOnce = async (taskId) => {
+    try {
+        return await getTask(taskId);
+    }
+    catch (error) {
+        // A brief network or server hiccup should not lose a paid task.
+        const retryable = error instanceof HydrillaError && (error.status === 0 || error.status >= 500);
+        if (!retryable) {
+            throw error;
+        }
+        return null;
+    }
+};
+/**
+ * Poll until the task finishes or the wait budget runs out. On timeout the
+ * task keeps running on Hydrilla and can be checked again with its id.
+ */
+export async function waitForTask(taskId, maxWaitMs, onProgress) {
+    const deadline = Date.now() + maxWaitMs;
+    const state = {
+        failures: 0,
+        last: { id: taskId, status: "PENDING" },
+    };
+    while (Date.now() < deadline) {
+        const task = await pollOnce(taskId);
+        if (task) {
+            state.failures = 0;
+            state.last = task;
+            if (isTerminal(task.status)) {
+                return { task, timedOut: false };
+            }
+            await onProgress(task);
+        }
+        else {
+            state.failures += 1;
+            if (state.failures > MAX_POLL_FAILURES) {
+                throw new HydrillaError("Lost contact with Hydrilla while waiting. Check the task again with hydrilla_get_task.");
+            }
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+    return { task: state.last, timedOut: true };
+}

package/dist/bridge.js

@@ -0,0 +1,102 @@
+/**
+ * Hydrilla Bridge: each Hydrilla plugin can listen on its own local port so a
+ * finished model can be sent straight into the open scene or project.
+ */
+export const APPS = ["blender", "maya", "3dsmax", "unreal", "unity", "godot"];
+const BRIDGE_HOST = "127.0.0.1";
+const BRIDGE_SERVICE = "hydrilla-bridge";
+const HEALTH_TIMEOUT_MS = 1_500;
+/** The plugin downloads the mesh before it replies. */
+const IMPORT_TIMEOUT_MS = 5 * 60_000;
+const BRIDGE_PORTS = {
+    blender: 7345,
+    maya: 7346,
+    "3dsmax": 7347,
+    unreal: 7348,
+    unity: 7349,
+    godot: 7350,
+};
+const APP_NAMES = {
+    blender: "Blender",
+    maya: "Maya",
+    "3dsmax": "3ds Max",
+    unreal: "Unreal Editor",
+    unity: "Unity",
+    godot: "Godot",
+};
+const BRIDGE_HINTS = {
+    blender: "In Blender, press N in the 3D viewport, open the Hydrilla tab and click Run Bridge.",
+    maya: "In Maya, open the Hydrilla window (import hydrilla_maya; hydrilla_maya.show()) and click Run Bridge.",
+    "3dsmax": "In 3ds Max, open the Hydrilla window (import hydrilla_max; hydrilla_max.show()) and click Run Bridge.",
+    unreal: "In Unreal Editor, choose Hydrilla > Run Bridge from the main menu.",
+    unity: "In Unity, open Window > Hydrilla and click Run Bridge.",
+    godot: "In Godot, open the Hydrilla dock and click Run Bridge.",
+};
+export class BridgeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BridgeError";
+    }
+}
+const bridgeUrl = (app) => `http://${BRIDGE_HOST}:${BRIDGE_PORTS[app]}`;
+export const appName = (app) => APP_NAMES[app];
+/** True when that app's Hydrilla plugin has its Bridge running. */
+export async function isAppListening(app) {
+    try {
+        const response = await fetch(`${bridgeUrl(app)}/health`, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            return false;
+        }
+        const data = (await response.json());
+        return data.service === BRIDGE_SERVICE;
+    }
+    catch {
+        // Nothing is listening on that port, or it is not a Hydrilla Bridge.
+        return false;
+    }
+}
+export async function listListeningApps() {
+    const checks = await Promise.all(APPS.map(async (app) => ({ app, listening: await isAppListening(app) })));
+    return checks.filter((check) => check.listening).map((check) => check.app);
+}
+const postImport = async (app, body) => {
+    try {
+        return await fetch(`${bridgeUrl(app)}/import`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(IMPORT_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new BridgeError(`${APP_NAMES[app]} stopped responding while receiving the model (${reason}).`);
+    }
+};
+const readBridgeError = async (response) => {
+    try {
+        const data = (await response.json());
+        return data.error || `status ${response.status}`;
+    }
+    catch {
+        // The plugin replied without a JSON body; the status code is all there is.
+        return `status ${response.status}`;
+    }
+};
+/** Hand a finished mesh to the app. The plugin downloads and imports it. */
+export async function sendMeshToApp(app, mesh) {
+    if (!(await isAppListening(app))) {
+        throw new BridgeError(`${APP_NAMES[app]} is not ready to receive models. ${BRIDGE_HINTS[app]} Then call hydrilla_send_to_app again with the same task_id; the model does not need to be generated again.`);
+    }
+    const response = await postImport(app, {
+        mesh_url: mesh.meshUrl,
+        name: mesh.name,
+        job_id: mesh.taskId,
+    });
+    if (!response.ok) {
+        throw new BridgeError(`${APP_NAMES[app]} could not import the model: ${await readBridgeError(response)}`);
+    }
+}

package/dist/config.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const SERVER_VERSION = "2.0.0";
+export const DEFAULT_API_BASE = "https://hydrilla-ai-g1bm.vercel.app";
+export const API_KEYS_URL = "https://hydrilla.ai/app/api-keys";
+/** Hosts that do not serve the developer API (old backend, GPU gateway). */
+const RETIRED_API_HOSTS = ["hydrilla-backend.vercel.app", "api.hydrilla.co", "api.hydrilla.ai"];
+function unquoteEnvValue(value) {
+    const quoted = (value.startsWith("\"") && value.endsWith("\"")) ||
+        (value.startsWith("'") && value.endsWith("'"));
+    if (quoted && value.length >= 2) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/** Load mcp.env next to the server. Claude Code does not read an envFile field. */
+export function loadLocalEnv() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const envPath = [join(here, "mcp.env"), join(here, "..", "mcp.env")].find((path) => existsSync(path));
+    if (!envPath) {
+        return;
+    }
+    const lines = readFileSync(envPath, "utf8").split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const eq = trimmed.indexOf("=");
+        if (eq <= 0) {
+            continue;
+        }
+        const key = trimmed.slice(0, eq).trim();
+        if (!key || process.env[key] !== undefined) {
+            continue;
+        }
+        process.env[key] = unquoteEnvValue(trimmed.slice(eq + 1).trim());
+    }
+}
+/**
+ * Config the Hydrilla plugins write when a key is pasted into one of them.
+ * Read on every call, so a key added in Blender works without restarting the agent.
+ */
+function readSharedConfig() {
+    const folder = (process.env.HYDRILLA_CONFIG_DIR || "").trim() || join(homedir(), ".hydrilla");
+    const path = join(folder, "config.json");
+    if (!existsSync(path)) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed && typeof parsed === "object") {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        // An unreadable shared file just means no shared key.
+        return {};
+    }
+}
+function cleanApiKey(value) {
+    const text = typeof value === "string" ? value.trim().replace(/^["']|["']$/g, "").trim() : "";
+    if (text.toLowerCase().startsWith("bearer ")) {
+        return text.slice(7).trim();
+    }
+    return text;
+}
+/** Key to use: the agent's MCP config first, else the one saved by a Hydrilla plugin. */
+export function resolveApiKey() {
+    const fromEnv = cleanApiKey(process.env.HYDRILLA_API_KEY || process.env.HYDRILLA_API_TOKEN);
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return cleanApiKey(readSharedConfig().api_key);
+}
+export function normalizeApiBase(value) {
+    const text = typeof value === "string" ? value.trim().replace(/\/+$/, "") : "";
+    if (!/^https?:\/\/\S+$/i.test(text)) {
+        return DEFAULT_API_BASE;
+    }
+    if (RETIRED_API_HOSTS.some((host) => text.toLowerCase().includes(host))) {
+        return DEFAULT_API_BASE;
+    }
+    return text;
+}
+export function resolveApiBase() {
+    const fromEnv = (process.env.HYDRILLA_API_BASE || "").trim();
+    if (fromEnv) {
+        return normalizeApiBase(fromEnv);
+    }
+    return normalizeApiBase(readSharedConfig().api_base);
+}
+/** Project token from env only. Secrets are never hardcoded. */
+export function getPostHogProjectToken() {
+    return (process.env.POSTHOG_PROJECT_TOKEN ||
+        process.env.POSTHOG_API_KEY ||
+        process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN ||
+        process.env.NEXT_PUBLIC_POSTHOG_KEY);
+}
+export function getPostHogHost() {
+    return (process.env.POSTHOG_HOST ||
+        process.env.NEXT_PUBLIC_POSTHOG_HOST ||
+        "https://us.i.posthog.com");
+}

package/dist/index.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { PostHog, instrument } from "@posthog/mcp";
+import { z } from "zod";
+import { CREATE_TIMEOUT_MS, api, getTask, waitForTask } from "./api.js";
+import { APPS, appName, listListeningApps, sendMeshToApp } from "./bridge.js";
+import { SERVER_VERSION, getPostHogHost, getPostHogProjectToken, loadLocalEnv } from "./config.js";
+loadLocalEnv();
+/** How long a generate call waits before handing back the task id to check later. */
+const MAX_WAIT_MS = 8 * 60_000;
+const jsonResult = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+});
+const errorResult = (error) => ({
+    content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+    isError: true,
+});
+/** Run a tool body and turn any failure into a readable tool error. */
+const guarded = async (work) => {
+    try {
+        return await work();
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+};
+/** Progress keeps long generations from hitting the client's request timeout. */
+const progressReporter = (extra) => async (task) => {
+    const progressToken = extra._meta?.progressToken;
+    if (progressToken === undefined) {
+        return;
+    }
+    try {
+        await extra.sendNotification({
+            method: "notifications/progress",
+            params: {
+                progressToken,
+                progress: Math.max(0, Math.min(99, Math.round(task.progress ?? 0))),
+                total: 100,
+                message: task.status_message || (task.status === "PENDING" ? "Waiting for a GPU" : "Generating"),
+            },
+        });
+    }
+    catch {
+        // Progress is a courtesy; the tool result still arrives without it.
+    }
+};
+const meshUrlOf = (task) => task.result?.mesh_url || "";
+/** Send a finished model to an app, reporting a failure without losing the result. */
+const deliver = async (task, app, name) => {
+    if (!app) {
+        return {};
+    }
+    try {
+        await sendMeshToApp(app, { meshUrl: meshUrlOf(task), name, taskId: task.id });
+        return { sent_to: appName(app) };
+    }
+    catch (error) {
+        return { send_error: error instanceof Error ? error.message : String(error) };
+    }
+};
+/** Wait for a created task and, if asked, place the model in the user's open app. */
+const finishGeneration = async (taskId, options, extra) => {
+    if (!options.wait) {
+        return jsonResult({
+            id: taskId,
+            status: "PENDING",
+            note: "Generation started. Check it with hydrilla_get_task; send it to an app with hydrilla_send_to_app once it has succeeded.",
+        });
+    }
+    const { task, timedOut } = await waitForTask(taskId, MAX_WAIT_MS, progressReporter(extra));
+    if (timedOut) {
+        return jsonResult({
+            ...task,
+            id: taskId,
+            note: "Still generating. Call hydrilla_get_task with this id in a minute; do not start the generation again.",
+        });
+    }
+    if (task.status !== "SUCCEEDED") {
+        return errorResult(new Error(task.error || `Generation ${task.status.toLowerCase()}.`));
+    }
+    const delivery = await deliver({ ...task, id: taskId }, options.sendTo, options.name);
+    return jsonResult({ ...task, id: taskId, ...delivery });
+};
+const server = new McpServer({
+    name: "hydrilla",
+    version: SERVER_VERSION,
+});
+const posthogToken = getPostHogProjectToken();
+const posthog = posthogToken
+    ? new PostHog(posthogToken, {
+        host: getPostHogHost(),
+        // Stdio processes exit quickly; flush aggressively so tool-call events land.
+        flushAt: 1,
+        flushInterval: 0,
+    })
+    : null;
+if (posthog) {
+    instrument(server, posthog, {
+        // Stdio must not write analytics warnings to stdout (corrupts MCP framing).
+        logger: (message) => {
+            process.stderr.write(`[posthog-mcp] ${message}\n`);
+        },
+    });
+}
+const shutdownPostHog = async () => {
+    if (!posthog) {
+        return;
+    }
+    try {
+        await posthog.shutdown();
+    }
+    catch {
+        // Analytics must never break the MCP process.
+    }
+};
+const exitAfterFlush = async () => {
+    await shutdownPostHog();
+    process.exit(0);
+};
+process.once("SIGTERM", () => {
+    void exitAfterFlush();
+});
+process.once("SIGINT", () => {
+    void exitAfterFlush();
+});
+const sendToSchema = z
+    .enum(APPS)
+    .optional()
+    .describe("Put the finished model straight into this open app (the app's Hydrilla plugin must have its Bridge running). Use when the user asks for the model in their scene or project.");
+const nameSchema = z
+    .string()
+    .max(48)
+    .optional()
+    .describe("Short name for the imported object, e.g. 'treasure-chest'");
+server.tool("hydrilla_me", "Return the Hydrilla account plan and credit balance. Free; use it to check the connection.", {}, async () => guarded(async () => jsonResult(await api("/v1/user/me"))));
+server.tool("hydrilla_text_to_3d", "Generate a textured 3D model (GLB) from a text prompt. Costs credits and takes a few minutes. Set send_to to place it in the user's open Blender, Unity, Unreal, Godot, Maya or 3ds Max.", {
+    prompt: z.string().min(1).describe("What to generate"),
+    wait: z.boolean().optional().describe("Wait until the model is ready (default true)"),
+    send_to: sendToSchema,
+    name: nameSchema,
+}, async ({ prompt, wait = true, send_to, name }, extra) => guarded(async () => {
+    const created = await api("/v1/3d/text-to-3d", { method: "POST", body: JSON.stringify({ prompt }) }, CREATE_TIMEOUT_MS);
+    return finishGeneration(created.id, { wait, sendTo: send_to, name }, extra);
+}));
+server.tool("hydrilla_image_to_3d", "Generate a textured 3D model (GLB) from a public image URL. Costs credits and takes a few minutes. Set send_to to place it in the user's open app.", {
+    image_url: z.string().url().describe("Public image URL"),
+    wait: z.boolean().optional().describe("Wait until the model is ready (default true)"),
+    send_to: sendToSchema,
+    name: nameSchema,
+}, async ({ image_url, wait = true, send_to, name }, extra) => guarded(async () => {
+    const created = await api("/v1/3d/image-to-3d", { method: "POST", body: JSON.stringify({ image_url }) }, CREATE_TIMEOUT_MS);
+    return finishGeneration(created.id, { wait, sendTo: send_to, name }, extra);
+}));
+server.tool("hydrilla_get_task", "Check a Hydrilla 3D task by id. Returns its status and, once it has succeeded, the mesh URL.", {
+    task_id: z.string().min(1),
+}, async ({ task_id }) => guarded(async () => jsonResult(await getTask(task_id))));
+server.tool("hydrilla_list_tasks", "List the user's recent Hydrilla 3D models, newest first. Free. Use it to find a model that already exists instead of generating it again.", {
+    limit: z.number().int().min(1).max(100).optional().describe("How many to return (default 20)"),
+}, async ({ limit = 20 }) => guarded(async () => jsonResult(await api(`/v1/3d/tasks?limit=${limit}`))));
+server.tool("hydrilla_cancel_task", "Stop a Hydrilla 3D task that is still generating. Unused credits are refunded.", {
+    task_id: z.string().min(1),
+}, async ({ task_id }) => guarded(async () => jsonResult(await api(`/v1/3d/tasks/${encodeURIComponent(task_id)}`, { method: "DELETE" }))));
+server.tool("hydrilla_list_apps", "List which of the user's apps (Blender, Maya, 3ds Max, Unreal, Unity, Godot) are open with the Hydrilla Bridge running and can receive a model right now. Free.", {}, async () => guarded(async () => {
+    const listening = await listListeningApps();
+    return jsonResult({
+        ready: listening,
+        note: listening.length > 0
+            ? "Pass one of these as send_to, or use hydrilla_send_to_app."
+            : "No app is listening. Ask the user to open the Hydrilla plugin in their app and click Run Bridge.",
+    });
+}));
+server.tool("hydrilla_send_to_app", "Put an already generated model into the user's open app (Blender, Unity, Unreal, Godot, Maya or 3ds Max). Free; does not generate anything.", {
+    app: z.enum(APPS).describe("Which app to send the model to"),
+    task_id: z.string().min(1).describe("Id of a task that has succeeded"),
+    name: nameSchema,
+}, async ({ app, task_id, name }) => guarded(async () => {
+    const task = await getTask(task_id);
+    if (task.status !== "SUCCEEDED" || !meshUrlOf(task)) {
+        return errorResult(new Error(`Task ${task_id} is ${task.status}, so there is no model to send yet. Check it with hydrilla_get_task.`));
+    }
+    await sendMeshToApp(app, { meshUrl: meshUrlOf(task), name, taskId: task_id });
+    return jsonResult({ id: task_id, sent_to: appName(app) });
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.once("beforeExit", () => {
+    void shutdownPostHog();
+});

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "hydrilla-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "MCP server for Hydrilla: generate 3D models and send them into Blender, Unity, Unreal, Godot, Maya or 3ds Max.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hydrilla",
+    "3d",
+    "text-to-3d",
+    "image-to-3d",
+    "blender",
+    "unity",
+    "unreal",
+    "godot"
+  ],
+  "homepage": "https://hydrilla.ai/integrations/mcp",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "hydrilla-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": "^20.20.0 || >=22.22.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@posthog/mcp": "^1.0.0",
+    "posthog-node": "^5.63.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}