streamby-core 0.37.0 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.38.0
+
+### Added
+
+- **Uploading and downloading files from the MCP server**, so an agent can bring files from and
+  to the tools it works with (Blender's or Godot's own MCP, a script). The file never goes
+  through the conversation: the tools give signed URLs, and the tool that has the file uploads
+  or downloads it directly. See the README for an example with Blender.
+  - `request_asset_upload` (`assets:write`): a new asset, or a new version of one, and the URL
+    to upload its file to.
+  - `get_asset_download_url` (`assets:read`): a URL to download an asset's file, its latest
+    version or an earlier one. `list_asset_versions` lists them.
+- **Asset versions are kept, and an asset's URL doesn't change when it's replaced.** A new
+  version (`replace-url`, from the UI too) is still uploaded to the asset's own key, so a site
+  that links to the asset shows the new one. Before that, the current version is copied to a
+  key of its own, `<key>.v<n>.<ext>`, and recorded in `asset_versions` (an asset's first
+  version is recorded on upload; an older asset gets it when it's first replaced). If it can't
+  be copied, nothing is replaced and no upload URL is given. The `replace-url` routes answer
+  the new version's `versionId` and `version`. Deleting an asset deletes every key of it.
+  - New `StorageAdapter.copyFile`, implemented by the S3 adapter. With an adapter without it,
+    asking for a new version answers 501.
+  - StreamBy doesn't set `Cache-Control` on uploads, so a browser or a CDN may serve a replaced
+    asset's earlier version for a while: set it where the files are served (see the README).
+- `GET /projects/:projectId/assets/:fileId/download-url` (`?versionId=` for an earlier version):
+  a signed URL that downloads the file with its name, wherever it's stored.
+- **Deliverables**: an asset, or one of its versions, delivered for a production shot or for an
+  export, kept in the NoSQL database's `deliverables` collection. `GET`, `POST` and
+  `DELETE /projects/:projectId/deliverables` list (by `shotId` or `exportId`), mark and remove
+  them; `list_deliverables`, `mark_deliverable` and `remove_deliverable` in the MCP server.
+  Deleting a shot, a sequence, an export or an asset removes its deliverables.
+- **`mcp.signedUrlTtl`**: how long the signed URLs given to an API token work, also when it
+  lists files. Default: 15 minutes to upload, 5 to download. A session's are as before.
+- `StorageAdapter.getPresignedUploadUrl` and `getPresignedGetUrl` take how long the URL works
+  (and `getPresignedGetUrl` the name to download it with).
+
+- `GET /projects/:id` answers `hasProductionData`: whether the project has production
+  sequences, so a client can show them even without a production node in its workflow.
+
+### Changed
+
+- **Production data is checked before it's saved.** Sequences, shots and tasks need a name
+  that isn't blank; a status must be `todo`, `in_progress`, `review` or `done`, and a task's
+  priority `low`, `medium` or `high`; a shot's `assignedTo` must list active members of the
+  project, and a task's be one of them (or null); a due date must be a date. Otherwise they
+  answer 400. A shot is made only in a sequence of the project, and a task only in a shot of
+  it (404 otherwise).
+- The MCP tools for shots take `assignedTo` as a list of user ids, as the API does, and their
+  statuses and priorities are listed in their schema.
+- **The MCP tools take the path a user does.** `create_sequence`, `create_shot` and
+  `create_task` first add a production node (a Shot node) to the project's workflow when it
+  has none, as dropping one on the canvas does, and make nothing if it can't be added. So they
+  need `workflow:write` as well as `production:write`. Each tool's description says where its
+  result shows in the UI.
+
+### Fixed
+
+- **Deleting production data leaves nothing behind.** Deleting a sequence deletes its shots'
+  tasks too (they were left), and deleting a project deletes its sequences, shots, tasks and
+  deliverables. Deleting a sequence that doesn't exist answers 404.
+- **Only editors and admins upload a new version of an asset.** The `replace-url` routes let
+  any member of the project, a viewer included, replace an asset's file.
+- The ingest job no longer records a second version of the file an upload already recorded.
+
 ## 0.37.0
 
 ### ⚠️ Breaking changes

package/README.md

@@ -203,12 +203,72 @@ A token sees only the tools whose permissions it has.
 | `get_export` | `exports:read` |
 | `get_job` | `jobs:read` |
 | `list_sequences`, `list_shots`, `list_tasks` | `production:read` |
-| `create_sequence`, `update_sequence`, `create_shot`, `update_shot`, `create_task`, `update_task` | `production:write` |
+| `update_sequence`, `update_shot`, `update_task` | `production:write` |
+| `create_sequence`, `create_shot`, `create_task` | `production:write` and `workflow:write` |
 | `delete_sequence`, `delete_shot`, `delete_task` | `production:delete` |
+| `list_asset_versions`, `get_asset_download_url`, `list_deliverables` | `assets:read` |
+| `request_asset_upload`, `mark_deliverable`, `remove_deliverable` | `assets:write` |
+
+The tools take the path a user does in the UI, and each one's description says where its
+result shows there. Production data lives under a production node of the project's workflow:
+if the workflow has none yet, `create_sequence`, `create_shot` and `create_task` first add a
+Shot node to it, as dropping one on the canvas does (so they need `workflow:write`), and make
+nothing if it can't be added.
 
 The tools that delete are marked as destructive (`destructiveHint`), so a client can ask before
 running them.
 
+**Files**
+
+A file never goes through the conversation. `request_asset_upload` makes a new asset (or a new
+version of one) and gives a signed URL to `PUT` its bytes to; `get_asset_download_url` gives a
+signed URL to `GET` an asset's file, its latest version or any earlier one. The tool that has
+the file uploads or downloads it directly, for example Blender's or Godot's own MCP server,
+which can run code. Each URL is for that one file, and given to an API token it works only
+briefly: 15 minutes to upload, 5 to download (`mcp.signedUrlTtl`).
+
+**Versions.** Replacing an asset doesn't change its URL: the new version is uploaded to the
+asset's own key, so a site that links to the asset shows the new one with no deploy. Before
+that, the current version is copied to a key of its own (`<key>.v<n>.<ext>`) and recorded, so
+every earlier version can still be downloaded by its id; if it can't be copied, nothing is
+replaced. A storage adapter keeps versions only if it can copy (`copyFile`; the S3 one does);
+otherwise asking for a new version answers 501. Deleting the asset deletes every key of it.
+
+Since the URL stays the same, a browser or a CDN may keep serving the earlier version for a
+while. StreamBy doesn't set `Cache-Control` on uploads (a signed URL that did would require
+every client to send the same header): set it where the files are served, for example a short
+`max-age` or `no-cache` on the CDN in front of the bucket, or invalidate the path when an asset
+is replaced.
+
+A **deliverable** is an asset, or one of its versions, delivered for a
+production shot or for an export; a shot or an export can have several, and the shot's panel
+in the UI shows them.
+
+For example, with Claude connected to StreamBy and to Blender's MCP server, asking *"export the
+scene as glTF and deliver it for shot SH010 of Portfolio"* goes:
+
+1. `list_projects`, `list_sequences`, `list_shots`: the project and the shot's id.
+2. `request_asset_upload` with `category: '3d-models'`, `fileName: 'SH010_layout.glb'` and
+   `contentType: 'model/gltf-binary'`: the new asset's id, and where to upload it.
+3. In Blender, code that exports the scene and uploads it:
+
+   ```python
+   import bpy, urllib.request
+   path = bpy.app.tempdir + "SH010_layout.glb"
+   bpy.ops.export_scene.gltf(filepath=path, export_format="GLB")
+   with open(path, "rb") as f:
+       req = urllib.request.Request(UPLOAD_URL, data=f.read(), method="PUT",
+                                    headers={"Content-Type": "model/gltf-binary"})
+   urllib.request.urlopen(req)
+   ```
+
+4. `mark_deliverable` with the asset's id and `shotId`: it shows in the shot's panel.
+
+Bringing an asset into Blender or Godot is the other way around: `get_asset_download_url`, and
+code there that downloads the URL and imports the file (in Blender,
+`bpy.ops.import_scene.gltf(filepath=...)`). A new version of the same asset is
+`request_asset_upload` with its `assetId`.
+
 **Limits and audit**
 
 - Each token can make at most 120 requests a minute (a sliding window). Past that, StreamBy
@@ -224,6 +284,7 @@ createStreamByRouter({
   // ...
   mcp: {
     rateLimit: { requests: 120, windowMs: 60_000 }, // the default
+    signedUrlTtl: { upload: 900, download: 300 },   // the default, in seconds
     // apiBaseUrl: 'http://127.0.0.1:3000/streamby', // where tools reach the REST API;
     //   by default this same process, at the request's local port and mount path
   },

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>;

package/dist/mcp/workflowNodes.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newShotNode = void 0;
+exports.ensureWorkflowNode = ensureWorkflowNode;
+const crypto_1 = __importDefault(require("crypto"));
+const manager_1 = require("../models/manager");
+const auth_1 = require("../utils/auth");
+const auth_2 = require("../services/auth");
+// The node types that make a workflow's production section (as the UI groups them).
+const PRODUCTION_NODE_TYPES = new Set(['shotNode', 'assemblyNode', 'masterNode']);
+/** A Shot node, as the UI makes one dropped on the canvas without a position. */
+const newShotNode = () => ({
+    id: `shotNode-${crypto_1.default.randomUUID()}`,
+    type: 'shotNode',
+    position: { x: 240 + Math.random() * 60, y: 300 + Math.random() * 40 },
+    data: { label: 'Shot', subtitle: 'Raw video clip', bgColor: '#0e2537', iconColor: '#38B6FF' },
+});
+exports.newShotNode = newShotNode;
+/**
+ * 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.
+ */
+async function ensureWorkflowNode(requirement, projectId, auth, api) {
+    if (requirement !== 'production' || !projectId)
+        return null;
+    if (!(0, auth_2.scopeReachesProject)(auth.apiToken, projectId))
+        return null;
+    const project = await (0, manager_1.getModel)('projects').findOne({ _id: projectId });
+    if (!project || !(0, auth_1.activeMemberOf)(project, auth.userId))
+        return null;
+    const schema = project.workflow?.nodeSchema ?? null;
+    const nodes = Array.isArray(schema?.nodes) ? schema.nodes : [];
+    if (nodes.some(node => PRODUCTION_NODE_TYPES.has(node?.type)))
+        return null;
+    const answer = await api({
+        method: 'PATCH',
+        path: `/projects/${encodeURIComponent(projectId)}/workflow`,
+        body: { nodeSchema: { ...(schema ?? {}), nodes: [...nodes, (0, exports.newShotNode)()], edges: Array.isArray(schema?.edges) ? schema.edges : [] } },
+    });
+    if (answer.status >= 200 && answer.status < 300)
+        return null;
+    const message = answer.body?.message ?? answer.body?.error;
+    return `Couldn't add a production node to the project's workflow: ${typeof message === 'string' ? message : `StreamBy answered ${answer.status}`}`;
+}

package/dist/middleware/createRouter.js

@@ -38,6 +38,7 @@ const production_1 = require("./routes/production");
 const rights_1 = require("./routes/rights");
 const workflow_1 = require("./routes/workflow");
 const pipeline_1 = require("./routes/pipeline");
+const deliverable_1 = require("./routes/deliverable");
 function createStreamByRouter(config) {
     const router = express_1.default.Router();
     if (config.encrypt)
@@ -134,5 +135,6 @@ function createStreamByRouter(config) {
     router.use((0, rights_1.rightsRouter)(config));
     router.use((0, workflow_1.workflowRouter)(config));
     router.use((0, pipeline_1.pipelineRouter)(config));
+    router.use((0, deliverable_1.deliverableRouter)(config));
     return router;
 }

package/dist/middleware/routes/deliverable.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'express';
+import { StreamByConfig } from '../../types';
+export declare function deliverableRouter(_config: StreamByConfig): Router;