streamby-core 0.37.0 → 0.39.0

package/dist/adapters/database/connectionManager.js

@@ -43,157 +43,157 @@ const getConnection = (id) => {
 exports.getConnection = getConnection;
 const ensureTablesExist = async (pool) => {
     try {
-        await pool.query(`
-      CREATE SCHEMA IF NOT EXISTS streamby;
-      CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+        await pool.query(`
+      CREATE SCHEMA IF NOT EXISTS streamby;
+      CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
     `);
         // Migrate id column from UUID to TEXT if it was created with the old schema
-        await pool.query(`
-      DO $$ BEGIN
-        ALTER TABLE streamby.projects ALTER COLUMN id TYPE TEXT USING id::text;
-        ALTER TABLE streamby.projects ALTER COLUMN id SET DEFAULT uuid_generate_v4()::text;
-      EXCEPTION WHEN OTHERS THEN NULL; END $$;
+        await pool.query(`
+      DO $$ BEGIN
+        ALTER TABLE streamby.projects ALTER COLUMN id TYPE TEXT USING id::text;
+        ALTER TABLE streamby.projects ALTER COLUMN id SET DEFAULT uuid_generate_v4()::text;
+      EXCEPTION WHEN OTHERS THEN NULL; END $$;
     `);
-        await pool.query(`
-      CREATE TABLE IF NOT EXISTS streamby.projects (
-        id               TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
-        name             VARCHAR(255) NOT NULL,
-        description      TEXT,
-        image            TEXT,
-        "allowedOrigin"  JSONB DEFAULT '[]',
-        exports          JSONB DEFAULT '[]',
-        connections      JSONB DEFAULT '[]',
-        "dbConnections"  JSONB DEFAULT '[]',
-        "dbType"         VARCHAR(50) NOT NULL DEFAULT 'sql',
-        "createdAt"      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-        "updatedAt"      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-      );
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.projects (
+        id               TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        name             VARCHAR(255) NOT NULL,
+        description      TEXT,
+        image            TEXT,
+        "allowedOrigin"  JSONB DEFAULT '[]',
+        exports          JSONB DEFAULT '[]',
+        connections      JSONB DEFAULT '[]',
+        "dbConnections"  JSONB DEFAULT '[]',
+        "dbType"         VARCHAR(50) NOT NULL DEFAULT 'sql',
+        "createdAt"      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        "updatedAt"      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+      );
     `);
         console.log('✅ "projects" table ensured to exist.');
         // Add JSONB columns to existing tables that predate this schema version
-        await pool.query(`
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "allowedOrigin"     JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS exports             JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS connections         JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "dbConnections"     JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "storageConnections" JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS workflow            JSONB;
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS pipelines           JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "builtinBackfilledAt" TIMESTAMP WITH TIME ZONE;
-      -- Written when a project is made (routes/project) and by its connection routes.
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS public              BOOLEAN DEFAULT TRUE;
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS category            TEXT;
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "integrationConnections"  JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "distributionConnections" JSONB DEFAULT '[]';
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "renderFarmConnections"   JSONB DEFAULT '[]';
+        await pool.query(`
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "allowedOrigin"     JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS exports             JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS connections         JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "dbConnections"     JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "storageConnections" JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS workflow            JSONB;
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS pipelines           JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "builtinBackfilledAt" TIMESTAMP WITH TIME ZONE;
+      -- Written when a project is made (routes/project) and by its connection routes.
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS public              BOOLEAN DEFAULT TRUE;
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS category            TEXT;
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "integrationConnections"  JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "distributionConnections" JSONB DEFAULT '[]';
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "renderFarmConnections"   JSONB DEFAULT '[]';
     `);
         // Ensure dbType exists with a non-null default
-        await pool.query(`
-      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "dbType" VARCHAR(50) NOT NULL DEFAULT 'sql';
+        await pool.query(`
+      ALTER TABLE streamby.projects ADD COLUMN IF NOT EXISTS "dbType" VARCHAR(50) NOT NULL DEFAULT 'sql';
     `);
-        await pool.query(`
-      CREATE TABLE IF NOT EXISTS streamby.project_members (
-        id           TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
-        "projectId"  TEXT NOT NULL REFERENCES streamby.projects(id) ON DELETE CASCADE,
-        "userId"     VARCHAR(255) NOT NULL,
-        role         VARCHAR(255) NOT NULL DEFAULT 'member',
-        status       VARCHAR(50) NOT NULL DEFAULT 'active',
-        archived     BOOLEAN NOT NULL DEFAULT FALSE,
-        "archivedBy" VARCHAR(255),
-        "archivedAt" TIMESTAMP WITH TIME ZONE,
-        "createdAt"  TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-        "updatedAt"  TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-        UNIQUE ("projectId", "userId")
-      );
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.project_members (
+        id           TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        "projectId"  TEXT NOT NULL REFERENCES streamby.projects(id) ON DELETE CASCADE,
+        "userId"     VARCHAR(255) NOT NULL,
+        role         VARCHAR(255) NOT NULL DEFAULT 'member',
+        status       VARCHAR(50) NOT NULL DEFAULT 'active',
+        archived     BOOLEAN NOT NULL DEFAULT FALSE,
+        "archivedBy" VARCHAR(255),
+        "archivedAt" TIMESTAMP WITH TIME ZONE,
+        "createdAt"  TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        "updatedAt"  TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        UNIQUE ("projectId", "userId")
+      );
     `);
-        await pool.query(`
-      ALTER TABLE streamby.project_members ADD COLUMN IF NOT EXISTS status VARCHAR(50) NOT NULL DEFAULT 'active';
+        await pool.query(`
+      ALTER TABLE streamby.project_members ADD COLUMN IF NOT EXISTS status VARCHAR(50) NOT NULL DEFAULT 'active';
     `);
         console.log('✅ "project_members" table ensured to exist.');
         // Migrate projectId FK column from UUID to TEXT if table predates this schema version
-        await pool.query(`
-      DO $$ BEGIN
-        ALTER TABLE streamby.project_members DROP CONSTRAINT IF EXISTS project_members_projectId_fkey;
-        ALTER TABLE streamby.project_members ALTER COLUMN "projectId" TYPE TEXT;
-        ALTER TABLE streamby.project_members ADD CONSTRAINT project_members_projectid_fkey
-          FOREIGN KEY ("projectId") REFERENCES streamby.projects(id) ON DELETE CASCADE;
-      EXCEPTION WHEN OTHERS THEN NULL; END $$;
+        await pool.query(`
+      DO $$ BEGIN
+        ALTER TABLE streamby.project_members DROP CONSTRAINT IF EXISTS project_members_projectId_fkey;
+        ALTER TABLE streamby.project_members ALTER COLUMN "projectId" TYPE TEXT;
+        ALTER TABLE streamby.project_members ADD CONSTRAINT project_members_projectid_fkey
+          FOREIGN KEY ("projectId") REFERENCES streamby.projects(id) ON DELETE CASCADE;
+      EXCEPTION WHEN OTHERS THEN NULL; END $$;
     `);
-        await pool.query(`
-      CREATE TABLE IF NOT EXISTS streamby.exports (
-        id          TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
-        "projectId" TEXT NOT NULL REFERENCES streamby.projects(id) ON DELETE CASCADE,
-        status      VARCHAR(50) NOT NULL DEFAULT 'pending',
-        "filePath"  TEXT,
-        "createdAt" TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-        "updatedAt" TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-      );
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.exports (
+        id          TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        "projectId" TEXT NOT NULL REFERENCES streamby.projects(id) ON DELETE CASCADE,
+        status      VARCHAR(50) NOT NULL DEFAULT 'pending',
+        "filePath"  TEXT,
+        "createdAt" TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        "updatedAt" TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+      );
     `);
         console.log('✅ "exports" table ensured to exist.');
         // user_integrations is registered against the main db only (see createRouter.ts), but
         // this function runs per-SQL-connection like projects/exports above — harmless on
         // non-main connections since the model never queries them there.
-        await pool.query(`
-      CREATE TABLE IF NOT EXISTS streamby.user_integrations (
-        id                     TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
-        "userId"               VARCHAR(255) NOT NULL,
-        kind                   VARCHAR(20) NOT NULL,
-        provider               VARCHAR(20) NOT NULL,
-        name                   VARCHAR(255) NOT NULL,
-        description            TEXT,
-        "encryptedCredential"  TEXT NOT NULL,
-        "createdAt"            TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-        "updatedAt"            TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-      );
-      CREATE INDEX IF NOT EXISTS user_integrations_userid_idx ON streamby.user_integrations ("userId");
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.user_integrations (
+        id                     TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        "userId"               VARCHAR(255) NOT NULL,
+        kind                   VARCHAR(20) NOT NULL,
+        provider               VARCHAR(20) NOT NULL,
+        name                   VARCHAR(255) NOT NULL,
+        description            TEXT,
+        "encryptedCredential"  TEXT NOT NULL,
+        "createdAt"            TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        "updatedAt"            TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+      );
+      CREATE INDEX IF NOT EXISTS user_integrations_userid_idx ON streamby.user_integrations ("userId");
     `);
         console.log('✅ "user_integrations" table ensured to exist.');
         // API tokens: only their hash is kept (see services/apiTokens). Main db only, like
         // user_integrations above. A table from before tokens had a kind and permissions gets the
         // new columns; its old tokens no longer work (they have no kind) and aren't listed.
-        await pool.query(`
-      CREATE TABLE IF NOT EXISTS streamby.api_tokens (
-        id                TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
-        kind              VARCHAR(10),
-        "userId"          VARCHAR(255) NOT NULL,
-        "createdByName"   VARCHAR(255),
-        name              VARCHAR(255) NOT NULL,
-        prefix            VARCHAR(32) NOT NULL,
-        hash              CHAR(64) NOT NULL UNIQUE,
-        permissions       JSONB NOT NULL DEFAULT '[]',
-        "projectIds"      JSONB NOT NULL,
-        "createdAt"       TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-        "expiresAt"       TIMESTAMP WITH TIME ZONE,
-        "lastUsedAt"      TIMESTAMP WITH TIME ZONE
-      );
-      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS kind VARCHAR(10);
-      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS "createdByName" VARCHAR(255);
-      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS permissions JSONB NOT NULL DEFAULT '[]';
-      DO $$ BEGIN
-        IF EXISTS (SELECT 1 FROM information_schema.columns
-                   WHERE table_schema = 'streamby' AND table_name = 'api_tokens' AND column_name = 'access') THEN
-          ALTER TABLE streamby.api_tokens ALTER COLUMN access DROP NOT NULL;
-        END IF;
-      END $$;
-      CREATE INDEX IF NOT EXISTS api_tokens_userid_idx ON streamby.api_tokens ("userId");
-      CREATE INDEX IF NOT EXISTS api_tokens_kind_idx ON streamby.api_tokens (kind);
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.api_tokens (
+        id                TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        kind              VARCHAR(10),
+        "userId"          VARCHAR(255) NOT NULL,
+        "createdByName"   VARCHAR(255),
+        name              VARCHAR(255) NOT NULL,
+        prefix            VARCHAR(32) NOT NULL,
+        hash              CHAR(64) NOT NULL UNIQUE,
+        permissions       JSONB NOT NULL DEFAULT '[]',
+        "projectIds"      JSONB NOT NULL,
+        "createdAt"       TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        "expiresAt"       TIMESTAMP WITH TIME ZONE,
+        "lastUsedAt"      TIMESTAMP WITH TIME ZONE
+      );
+      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS kind VARCHAR(10);
+      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS "createdByName" VARCHAR(255);
+      ALTER TABLE streamby.api_tokens ADD COLUMN IF NOT EXISTS permissions JSONB NOT NULL DEFAULT '[]';
+      DO $$ BEGIN
+        IF EXISTS (SELECT 1 FROM information_schema.columns
+                   WHERE table_schema = 'streamby' AND table_name = 'api_tokens' AND column_name = 'access') THEN
+          ALTER TABLE streamby.api_tokens ALTER COLUMN access DROP NOT NULL;
+        END IF;
+      END $$;
+      CREATE INDEX IF NOT EXISTS api_tokens_userid_idx ON streamby.api_tokens ("userId");
+      CREATE INDEX IF NOT EXISTS api_tokens_kind_idx ON streamby.api_tokens (kind);
     `);
         console.log('✅ "api_tokens" table ensured to exist.');
         // The MCP server's audit log: every tool call (see mcp/audit). Main db only.
-        await pool.query(`
-      CREATE TABLE IF NOT EXISTS streamby.mcp_audit (
-        id            TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
-        "userId"      VARCHAR(255) NOT NULL,
-        "tokenId"     VARCHAR(255) NOT NULL,
-        "projectId"   VARCHAR(255),
-        tool          VARCHAR(100) NOT NULL,
-        ok            BOOLEAN NOT NULL,
-        status        INTEGER,
-        error         TEXT,
-        "durationMs"  INTEGER NOT NULL,
-        "createdAt"   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-      );
-      CREATE INDEX IF NOT EXISTS mcp_audit_token_idx ON streamby.mcp_audit ("tokenId", "createdAt");
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.mcp_audit (
+        id            TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        "userId"      VARCHAR(255) NOT NULL,
+        "tokenId"     VARCHAR(255) NOT NULL,
+        "projectId"   VARCHAR(255),
+        tool          VARCHAR(100) NOT NULL,
+        ok            BOOLEAN NOT NULL,
+        status        INTEGER,
+        error         TEXT,
+        "durationMs"  INTEGER NOT NULL,
+        "createdAt"   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+      );
+      CREATE INDEX IF NOT EXISTS mcp_audit_token_idx ON streamby.mcp_audit ("tokenId", "createdAt");
     `);
         console.log('✅ "mcp_audit" table ensured to exist.');
     }

package/dist/adapters/database/sql.js

@@ -10,7 +10,7 @@ function serializeForPg(v) {
 }
 const createSQLExportTable = async (connection, projectId, exportName, nodeSchema) => {
     const exportId = (0, crypto_1.randomUUID)();
-    await connection.query(`INSERT INTO "exports" (id, "projectId", node_schema, name, method, created_at, updated_at)
+    await connection.query(`INSERT INTO "exports" (id, "projectId", node_schema, name, method, created_at, updated_at)
      VALUES ($1, $2, $3, $4, 'GET', NOW(), NOW())`, [exportId, projectId, nodeSchema ? JSON.stringify(nodeSchema) : null, exportName]);
     return { exportId };
 };

package/dist/adapters/storage/s3.d.ts

@@ -8,8 +8,9 @@ export declare class S3Adapter implements StorageAdapter {
     deleteProjectDirectory(projectId: string): Promise<any>;
     getPresignedUrl(contentType: string, projectId: string): Promise<any>;
     getPresignedProjectImageUrl(projectId: string): Promise<any>;
-    getPresignedGetUrl(key: string): Promise<string>;
-    getPresignedUploadUrl(key: string, contentType: string): Promise<string>;
+    getPresignedGetUrl(key: string, expiresIn?: number, downloadName?: string): Promise<string>;
+    getPresignedUploadUrl(key: string, contentType: string, expiresIn?: number): Promise<string>;
+    copyFile(from: string, to: string): Promise<void>;
     deleteFile(key: string): Promise<void>;
     listFilesByCategory(projectId: string, category: string): Promise<StorageFileInfo[]>;
     private inferMimeType;

package/dist/adapters/storage/s3.js

@@ -64,13 +64,21 @@ class S3Adapter {
         const publicUrl = `https://${this.bucket}.s3.amazonaws.com/${key}`;
         return { url, publicUrl };
     }
-    async getPresignedGetUrl(key) {
-        const command = new client_s3_1.GetObjectCommand({ Bucket: this.bucket, Key: key });
-        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn: 86400 });
+    async getPresignedGetUrl(key, expiresIn = 86400, downloadName) {
+        const command = new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: key,
+            ...(downloadName ? { ResponseContentDisposition: contentDisposition(downloadName) } : {}),
+        });
+        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn });
     }
-    async getPresignedUploadUrl(key, contentType) {
+    async getPresignedUploadUrl(key, contentType, expiresIn = 3600) {
         const command = new client_s3_1.PutObjectCommand({ Bucket: this.bucket, Key: key, ContentType: contentType });
-        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn: 3600 });
+        return await (0, s3_request_presigner_1.getSignedUrl)(this.s3, command, { expiresIn });
+    }
+    async copyFile(from, to) {
+        const source = `${this.bucket}/${from.split('/').map(encodeURIComponent).join('/')}`;
+        await this.s3.send(new client_s3_1.CopyObjectCommand({ Bucket: this.bucket, CopySource: source, Key: to }));
     }
     async deleteFile(key) {
         const command = new client_s3_1.DeleteObjectCommand({ Bucket: this.bucket, Key: key });
@@ -114,3 +122,8 @@ class S3Adapter {
     }
 }
 exports.S3Adapter = S3Adapter;
+// An attachment with its name: ASCII in `filename`, the full name in `filename*` (RFC 6266).
+const contentDisposition = (name) => {
+    const ascii = name.replace(/[^\x20-\x7e]|["\\]/g, '_');
+    return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+};

package/dist/mcp/server.js

@@ -5,6 +5,7 @@ exports.createMcpServer = createMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const tools_1 = require("./tools");
 const audit_1 = require("./audit");
+const workflowNodes_1 = require("./workflowNodes");
 exports.MCP_SERVER_NAME = 'streamby';
 const errorText = (body, status) => {
     const message = body?.message ?? body?.error;
@@ -34,6 +35,17 @@ function createMcpServer(auth, api, config, version) {
             const projectId = tool.projectOf?.(args) ?? tokenProject;
             let status = null;
             try {
+                // What the workflow needs first, as a user would add it.
+                if (tool.workflowNode) {
+                    const refused = await (0, workflowNodes_1.ensureWorkflowNode)(tool.workflowNode, tool.projectOf?.(args), auth, api);
+                    if (refused) {
+                        await (0, audit_1.recordMcpCall)({
+                            userId: auth.userId, tokenId: auth.apiToken.tokenId, projectId, tool: tool.name,
+                            ok: false, status: null, error: refused, durationMs: Date.now() - started,
+                        }, config);
+                        return { isError: true, content: [{ type: 'text', text: refused }] };
+                    }
+                }
                 const answer = await api(tool.call(args));
                 status = answer.status;
                 const ok = status >= 200 && status < 300;

package/dist/mcp/tools.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { ApiTokenPermission } from '../services/apiTokenPermissions';
+import type { WorkflowNodeRequirement } from './workflowNodes';
 export interface ToolCall {
     method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
     path: string;
@@ -12,6 +13,7 @@ export interface ToolDefinition<S extends z.ZodRawShape = z.ZodRawShape> {
     permissions: ApiTokenPermission[];
     write?: boolean;
     destructive?: boolean;
+    workflowNode?: WorkflowNodeRequirement;
     input: S;
     projectOf?: (args: z.infer<z.ZodObject<S>>) => string | undefined;
     call: (args: z.infer<z.ZodObject<S>>) => ToolCall;

package/dist/mcp/tools.js

@@ -8,19 +8,20 @@ const projectId = id('project');
 const enc = encodeURIComponent;
 const byProject = ({ projectId }) => projectId;
 const CATEGORIES = ['images', 'audios', 'videos', '3d-models'];
+const STATUSES = ['todo', 'in_progress', 'review', 'done'];
 const shotFields = {
     description: zod_1.z.string().optional(),
-    status: zod_1.z.string().optional().describe('Its status, as the project uses them'),
-    assignedTo: zod_1.z.string().optional().describe("The assignee's user id"),
+    status: zod_1.z.enum(STATUSES).optional(),
+    assignedTo: zod_1.z.array(zod_1.z.string()).optional().describe("The assignees' user ids: members of the project"),
     assetId: zod_1.z.string().optional(),
     exportId: zod_1.z.string().optional(),
     dueDate: zod_1.z.string().optional().describe('An ISO 8601 date'),
     order: zod_1.z.number().optional(),
 };
 const taskFields = {
-    status: zod_1.z.string().optional(),
-    priority: zod_1.z.string().optional(),
-    assignedTo: zod_1.z.string().optional().describe("The assignee's user id"),
+    status: zod_1.z.enum(STATUSES).optional(),
+    priority: zod_1.z.enum(['low', 'medium', 'high']).optional(),
+    assignedTo: zod_1.z.string().optional().describe("The assignee's user id: a member of the project"),
     dueDate: zod_1.z.string().optional().describe('An ISO 8601 date'),
     notes: zod_1.z.string().optional(),
 };
@@ -156,21 +157,21 @@ exports.TOOLS = [
     // ── Writing ──
     tool({
         name: 'update_asset_metadata', title: "Update an asset's custom tags", permissions: ['assets:write'], write: true,
-        description: "Sets an asset's custom tags (key/value pairs), replacing the ones it had.",
+        description: "Sets an asset's custom tags (key/value pairs), replacing the ones it had. They show in the file's Metadata tab, in Storage.",
         input: { projectId, fileId: id('asset'), customTags: zod_1.z.record(zod_1.z.string(), zod_1.z.string()) },
         projectOf: byProject,
         call: ({ projectId, fileId, customTags }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/assets/${enc(fileId)}/metadata`, body: { customTags } }),
     }),
     tool({
         name: 'set_asset_rights', title: "Set an asset's rights", permissions: ['rights:write'], write: true,
-        description: "Sets an asset's rights: holder, license, territory, expiry, restrictions and notes.",
+        description: "Sets an asset's rights: holder, license, territory, expiry, restrictions and notes. They show in the file's Rights tab, in Storage.",
         input: { projectId, assetId: id('asset'), ...rightsFields },
         projectOf: byProject,
         call: ({ projectId, assetId, ...rights }) => ({ method: 'PUT', path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/rights`, body: defined(rights) }),
     }),
     tool({
         name: 'create_pipeline', title: 'Create a pipeline', permissions: ['workflow:write'], write: true,
-        description: 'Creates a pipeline in a project.',
+        description: "Creates a pipeline in a project. It shows under Pipelines, and the workflow canvas draws its node.",
         input: { projectId, name: zod_1.z.string().min(1), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
         projectOf: byProject,
         call: ({ projectId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/pipelines`, body: defined(fields) }),
@@ -183,8 +184,8 @@ exports.TOOLS = [
         call: ({ projectId, pipelineId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/pipelines/${enc(pipelineId)}`, body: defined(fields) }),
     }),
     tool({
-        name: 'create_sequence', title: 'Create a production sequence', permissions: ['production:write'], write: true,
-        description: 'Creates a production sequence in a project.',
+        name: 'create_sequence', title: 'Create a production sequence', permissions: ['production:write', 'workflow:write'], write: true, workflowNode: 'production',
+        description: "Creates a production sequence in a project, shown in its Production board. If the project's workflow has no production node yet, it first adds one (a Shot node, as dropping it on the canvas does), so the project's Production section shows it: that's why it also needs workflow:write.",
         input: { projectId, name: zod_1.z.string().min(1), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
         projectOf: byProject,
         call: ({ projectId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/production/sequences`, body: defined(fields) }),
@@ -197,8 +198,8 @@ exports.TOOLS = [
         call: ({ projectId, sequenceId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/production/sequences/${enc(sequenceId)}`, body: defined(fields) }),
     }),
     tool({
-        name: 'create_shot', title: 'Create a shot', permissions: ['production:write'], write: true,
-        description: 'Creates a shot in a production sequence.',
+        name: 'create_shot', title: 'Create a shot', permissions: ['production:write', 'workflow:write'], write: true, workflowNode: 'production',
+        description: "Creates a shot in a production sequence, shown in its Production board. If the project's workflow has no production node yet, it first adds one (a Shot node, as dropping it on the canvas does), so the project's Production section shows it: that's why it also needs workflow:write.",
         input: { projectId, sequenceId: id('sequence'), name: zod_1.z.string().min(1), ...shotFields },
         projectOf: byProject,
         call: ({ projectId, sequenceId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/production/sequences/${enc(sequenceId)}/shots`, body: defined(fields) }),
@@ -211,8 +212,8 @@ exports.TOOLS = [
         call: ({ projectId, shotId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}`, body: defined(fields) }),
     }),
     tool({
-        name: 'create_task', title: 'Create a shot task', permissions: ['production:write'], write: true,
-        description: 'Creates a task in a shot.',
+        name: 'create_task', title: 'Create a shot task', permissions: ['production:write', 'workflow:write'], write: true, workflowNode: 'production',
+        description: "Creates a task in a shot, shown in the shot's panel in the Production board. If the project's workflow has no production node yet, it first adds one (a Shot node, as dropping it on the canvas does), so the project's Production section shows it: that's why it also needs workflow:write.",
         input: { projectId, shotId: id('shot'), name: zod_1.z.string().min(1), ...taskFields },
         projectOf: byProject,
         call: ({ projectId, shotId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}/tasks`, body: defined(fields) }),
@@ -224,6 +225,98 @@ exports.TOOLS = [
         projectOf: byProject,
         call: ({ projectId, shotId, taskId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}/tasks/${enc(taskId)}`, body: defined(fields) }),
     }),
+    // ── Files: uploading, downloading, deliverables ──
+    // The file itself never goes through the conversation: these tools give a signed URL, and
+    // the user's own tool (Blender's or Godot's MCP, a script) uploads or downloads it directly.
+    tool({
+        name: 'list_asset_versions', title: "List an asset's versions", permissions: ['assets:read'],
+        description: "An asset's versions, newest first: each one's id, number, file name and when it was made. Any of them can be downloaded (get_asset_download_url).",
+        input: { projectId, assetId: id('asset') },
+        projectOf: byProject,
+        call: ({ projectId, assetId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/versions` }),
+        pick: (data) => (data?.versions ?? []).map((v) => ({
+            versionId: v.versionId, version: v.version, fileName: v.fileName ?? null, contentType: v.contentType ?? null, createdAt: v.createdAt,
+        })),
+    }),
+    tool({
+        name: 'request_asset_upload', title: 'Request an upload URL', permissions: ['assets:write'], write: true,
+        description: [
+            "Makes a new asset (or, with assetId, a new version of one) and gives a signed URL to upload its file to, as the UI does.",
+            "It doesn't upload anything: the file is sent by the tool that has it (for example Blender's MCP, running Python), with an HTTP PUT of its bytes to `upload.url` and the `upload.headers` given, before `expiresAt`.",
+            "The URL works for that file only. A new version keeps the asset's URL (it replaces what it serves); the earlier ones are archived and can still be downloaded.",
+            "Categories: images, audios, videos, 3d-models (.glb, .gltf, .obj, .fbx, .stl, .ply); contentType must match it.",
+        ].join(' '),
+        input: {
+            projectId,
+            category: zod_1.z.enum(CATEGORIES),
+            fileName: zod_1.z.string().min(1).describe('The file name, with its extension (e.g. shot010_layout.glb)'),
+            contentType: zod_1.z.string().min(1).describe('Its MIME type (e.g. model/gltf-binary, image/png, video/mp4)'),
+            assetId: zod_1.z.string().optional().describe('An existing asset to upload a new version of; a new asset if not given'),
+            connectionId: zod_1.z.string().optional().describe("A storage connection to store it in; the project's built-in storage if not given"),
+        },
+        projectOf: byProject,
+        call: ({ projectId, category, fileName, contentType, assetId, connectionId }) => {
+            const query = new URLSearchParams({ fileName, contentType, ...(connectionId && !assetId ? { category } : {}) });
+            const files = connectionId ? `/projects/${enc(projectId)}/connections/storage/${enc(connectionId)}` : `/projects/${enc(projectId)}/storage`;
+            const path = assetId
+                ? `${files}/files/${enc(assetId)}/replace-url`
+                : connectionId ? `${files}/upload-url` : `${files}/${category}/upload-url`;
+            return { method: 'GET', path: `${path}?${query}` };
+        },
+        pick: (data, { contentType }) => ({
+            assetId: data?.fileId,
+            ...(data?.versionId ? { versionId: data.versionId, version: data.version } : { version: 1 }),
+            upload: { method: 'PUT', url: data?.url, headers: { 'Content-Type': contentType } },
+            expiresAt: data?.expiresAt ?? null,
+        }),
+    }),
+    tool({
+        name: 'get_asset_download_url', title: 'Get a download URL', permissions: ['assets:read'],
+        description: "A short-lived signed URL to download an asset's file (its latest version, or the one given), for the tool that will use it (for example Blender's or Godot's MCP) to fetch with an HTTP GET before `expiresAt`. It works for that file only.",
+        input: { projectId, assetId: id('asset'), versionId: zod_1.z.string().optional().describe('A version (list_asset_versions); the latest if not given') },
+        projectOf: byProject,
+        call: ({ projectId, assetId, versionId }) => ({
+            method: 'GET',
+            path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/download-url${versionId ? `?${new URLSearchParams({ versionId })}` : ''}`,
+        }),
+    }),
+    tool({
+        name: 'list_deliverables', title: 'List deliverables', permissions: ['assets:read'],
+        description: "A project's deliverables (assets delivered for a shot or an export), of one shot or export if given: each one's asset, version, note and what it's for.",
+        input: {
+            projectId,
+            shotId: zod_1.z.string().optional().describe("A shot's id: only its deliverables"),
+            exportId: zod_1.z.string().optional().describe("An export's id: only its deliverables"),
+        },
+        projectOf: byProject,
+        call: ({ projectId, shotId, exportId }) => {
+            const query = new URLSearchParams(defined({ shotId, exportId })).toString();
+            return { method: 'GET', path: `/projects/${enc(projectId)}/deliverables${query ? `?${query}` : ''}` };
+        },
+        pick: (data) => data?.deliverables ?? [],
+    }),
+    tool({
+        name: 'mark_deliverable', title: 'Mark a deliverable', permissions: ['assets:write'], write: true,
+        description: "Marks an asset (or one of its versions) as a deliverable of a production shot or of an export. It shows in the shot's panel in the Production board, or in the export's Deliverables tab. Give shotId or exportId, one of them. Upload the file first (request_asset_upload).",
+        input: {
+            projectId,
+            assetId: id('asset'),
+            versionId: zod_1.z.string().optional().describe('A version of it; without one, the asset as it is (its latest version)'),
+            shotId: zod_1.z.string().optional().describe("The shot it's delivered for"),
+            exportId: zod_1.z.string().optional().describe("The export it's delivered for"),
+            note: zod_1.z.string().max(1000).optional(),
+        },
+        projectOf: byProject,
+        call: ({ projectId, ...fields }) => ({ method: 'POST', path: `/projects/${enc(projectId)}/deliverables`, body: defined(fields) }),
+        pick: (data) => data?.deliverable,
+    }),
+    tool({
+        name: 'remove_deliverable', title: 'Remove a deliverable', permissions: ['assets:write'], write: true,
+        description: 'Unmarks a deliverable. Its asset stays where it is.',
+        input: { projectId, deliverableId: id('deliverable') },
+        projectOf: byProject,
+        call: ({ projectId, deliverableId }) => ({ method: 'DELETE', path: `/projects/${enc(projectId)}/deliverables/${enc(deliverableId)}` }),
+    }),
     // ── Projects ──
     tool({
         name: 'create_project', title: 'Create a project', permissions: ['projects:create'], write: true,

package/dist/mcp/workflowNodes.d.ts

@@ -0,0 +1,24 @@
+import { Auth } from '../types';
+import type { ApiCaller } from './server';
+export type WorkflowNodeRequirement = 'production';
+/** A Shot node, as the UI makes one dropped on the canvas without a position. */
+export declare const newShotNode: () => {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: {
+        label: string;
+        subtitle: string;
+        bgColor: string;
+        iconColor: string;
+    };
+};
+/**
+ * Makes sure a project's workflow has what `requirement` needs, adding it (through the REST
+ * API, as the caller) if it's missing. An error to answer with, or null to go on. A project
+ * the caller doesn't reach is left alone: the call that follows answers for it.
+ */
+export declare function ensureWorkflowNode(requirement: WorkflowNodeRequirement, projectId: string | undefined, auth: Auth, api: ApiCaller): Promise<string | null>;