streamby-core 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.36.0
+
+### Added
+
+- **MCP server** at `POST /mcp`, for agents such as Claude Code to work with StreamBy projects
+  with an API token (see the README).
+  - It takes only an API token.
+  - Its tools call the REST API with that token, so they reach exactly what the token and its
+    owner can, and writes are saved as the UI's are.
+  - **Reading tools:** projects, assets with their metadata and rights, workflow, pipelines,
+    exports, jobs, and production sequences, shots and tasks.
+  - **Writing tools**, listed only for `write` tokens: asset metadata and rights, pipelines,
+    sequences, shots and tasks.
+- **`mcp.rateLimit`** (default 120 requests a minute per token; past it, 429 with
+  `Retry-After`) and **`mcp.apiBaseUrl`** in the router config.
+- **New table: `mcp_audit`.** It's created at startup in the main database. Every tool call is
+  recorded there, with the user, token, project, tool and result, but never the arguments nor
+  the token.
+- New dependencies: `@modelcontextprotocol/sdk` and `zod`.
+
+### Fixed
+
+- **Projects can be made with PostgreSQL as the main database.** The `projects` table that
+  StreamBy creates at startup was missing columns the routes write: `public`, `category`,
+  `integrationConnections`, `distributionConnections` and `renderFarmConnections`.
+  - Making a project failed with `column "public" does not exist`.
+  - Adding service, distribution or render farm connections failed too.
+  - They're added at startup now, only where they're missing; databases that already have
+    them aren't changed.
+
 ## 0.35.0
 
 ### Added

package/README.md

@@ -149,6 +149,99 @@ its owner can, and it stops reaching a project as soon as its owner leaves it.
 
 ---
 
+## 🤖 MCP server
+
+StreamBy serves an [MCP](https://modelcontextprotocol.io) server at `POST /streamby/mcp`
+(Streamable HTTP, stateless). Agents such as Claude Code use it to read and work on StreamBy
+projects with an API token (see above). It takes only an API token; a browser session gets 401.
+
+Each tool calls StreamBy's own REST API with the caller's token. So it reaches exactly what the
+token's scope and its owner's role in each project allow, and a write is saved just like one
+made from the UI, which shows it when it loads the project.
+
+**Tools**
+
+- **Reading**, with any token:
+  - `list_projects`, `get_project`;
+  - `list_assets` (by category, optionally in one storage connection, and filtered by name),
+    `get_asset_metadata`, `get_asset_rights`;
+  - `get_workflow`, `list_pipelines`, `get_pipeline`, `list_exports`, `get_export`;
+  - `get_job`;
+  - `list_sequences`, `list_shots`, `list_tasks`.
+- **Writing**, listed only for a `write` token, and allowed only where its owner is an editor or
+  an admin:
+  - `update_asset_metadata`, `set_asset_rights`;
+  - `create_pipeline`, `update_pipeline`;
+  - `create_sequence`, `update_sequence`, `create_shot`, `update_shot`, `create_task`,
+    `update_task`.
+
+**Limits and audit**
+
+- Each token can make at most 120 requests a minute (a sliding window). Past that, StreamBy
+  answers 429 with `Retry-After`. Each instance counts its own requests. Change the limit with
+  `mcp.rateLimit`.
+- Every tool call is recorded in the `mcp_audit` table, created at startup in the main database.
+  Each row has the user, the token's id, the project, the tool, whether it went through, the
+  status, the error and the duration. A row never includes the arguments or the token.
+
+```ts
+createStreamByRouter({
+  // ...
+  mcp: {
+    rateLimit: { requests: 120, windowMs: 60_000 }, // the default
+    // 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
+  },
+});
+```
+
+### Connecting from Claude Code
+
+Make an API token in StreamBy (Settings → Security → Personal API tokens), and keep it in an
+environment variable, never in a file:
+
+```bash
+export STREAMBY_TOKEN=sbt_...
+```
+
+Add the server to your project's `.mcp.json`. Claude Code expands `${STREAMBY_TOKEN}` from the
+environment:
+
+```json
+{
+  "mcpServers": {
+    "streamby": {
+      "type": "http",
+      "url": "https://your-host/streamby/mcp",
+      "headers": { "Authorization": "Bearer ${STREAMBY_TOKEN}" }
+    }
+  }
+}
+```
+
+### Connecting from Claude Desktop
+
+Claude Desktop runs local (stdio) servers from `claude_desktop_config.json`. Reach StreamBy
+through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), passing the token in its
+`env`. This file holds it in plain text, so use a token with only the scope you need, and
+an expiry:
+
+```json
+{
+  "mcpServers": {
+    "streamby": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://your-host/streamby/mcp", "--header", "Authorization:${STREAMBY_AUTH}"],
+      "env": { "STREAMBY_AUTH": "Bearer sbt_..." }
+    }
+  }
+}
+```
+
+The claude.ai connector needs OAuth, which isn't available yet: it's for API tokens only for now.
+
+---
+
 ## 👥 Project roles
 
 What a user can do in a project depends on their role in that project, as an active member

package/dist/adapters/database/connectionManager.js

@@ -80,11 +80,12 @@ const ensureTablesExist = async (pool) => {
       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;
-      -- Reverted: a project has no notion of a "default" database/storage connection —
-      -- each dataSourceNode/ingestNode always declares its own connection explicitly.
-      ALTER TABLE streamby.projects DROP COLUMN IF EXISTS "defaultDatabaseId";
-      ALTER TABLE streamby.projects DROP COLUMN IF EXISTS "defaultStorageId";
-      ALTER TABLE streamby.projects DROP COLUMN IF EXISTS "defaultConnectionsBackfilledAt";
+      -- 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(`
@@ -165,6 +166,23 @@ const ensureTablesExist = async (pool) => {
       CREATE INDEX IF NOT EXISTS api_tokens_userid_idx ON streamby.api_tokens ("userId");
     `);
         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");
+    `);
+        console.log('✅ "mcp_audit" table ensured to exist.');
     }
     catch (error) {
         console.error('❌ Error ensuring tables exist:', error);

package/dist/mcp/audit.d.ts

@@ -0,0 +1,12 @@
+import { StreamByConfig } from '../types';
+export interface McpAuditEntry {
+    userId: string;
+    tokenId: string;
+    projectId: string | null;
+    tool: string;
+    ok: boolean;
+    status: number | null;
+    error: string | null;
+    durationMs: number;
+}
+export declare function recordMcpCall(entry: McpAuditEntry, config: StreamByConfig): Promise<void>;

package/dist/mcp/audit.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordMcpCall = recordMcpCall;
+const crypto_1 = __importDefault(require("crypto"));
+const manager_1 = require("../models/manager");
+async function recordMcpCall(entry, config) {
+    try {
+        const dbType = config.databases?.find(db => db.main)?.type ?? 'nosql';
+        await (0, manager_1.getModel)('mcp_audit').create({ id: crypto_1.default.randomUUID(), ...entry, createdAt: new Date(), dbType });
+    }
+    catch (err) {
+        console.error('❌ StreamBy MCP: failed to record a tool call:', err instanceof Error ? err.message : err);
+    }
+}

package/dist/mcp/rateLimit.d.ts

@@ -0,0 +1,14 @@
+export interface RateLimit {
+    requests: number;
+    windowMs: number;
+}
+export declare const DEFAULT_MCP_RATE_LIMIT: RateLimit;
+export declare function createRateLimiter({ requests, windowMs }: RateLimit): {
+    /** Counts a request by `key`: whether it's allowed, and if not, how long until it would be. */
+    take(key: string, now?: number): {
+        allowed: true;
+    } | {
+        allowed: false;
+        retryAfterMs: number;
+    };
+};

package/dist/mcp/rateLimit.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MCP_RATE_LIMIT = void 0;
+exports.createRateLimiter = createRateLimiter;
+exports.DEFAULT_MCP_RATE_LIMIT = { requests: 120, windowMs: 60000 };
+function createRateLimiter({ requests, windowMs }) {
+    const seen = new Map();
+    return {
+        /** Counts a request by `key`: whether it's allowed, and if not, how long until it would be. */
+        take(key, now = Date.now()) {
+            const recent = (seen.get(key) ?? []).filter(at => at > now - windowMs);
+            if (recent.length >= requests) {
+                seen.set(key, recent);
+                return { allowed: false, retryAfterMs: recent[0] + windowMs - now };
+            }
+            recent.push(now);
+            seen.set(key, recent);
+            return { allowed: true };
+        },
+    };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Auth, StreamByConfig } from '../types';
+import { ToolCall } from './tools';
+export declare const MCP_SERVER_NAME = "streamby";
+export type ApiCaller = (call: ToolCall) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+/**
+ * An MCP server for one request of `auth` (an API token's owner): its tools, the writing ones
+ * only for a token with write access. Each tool call goes to the REST API through `api`, and is
+ * recorded in the audit log.
+ */
+export declare function createMcpServer(auth: Auth, api: ApiCaller, config: StreamByConfig, version: string): McpServer;

package/dist/mcp/server.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_SERVER_NAME = void 0;
+exports.createMcpServer = createMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const tools_1 = require("./tools");
+const audit_1 = require("./audit");
+exports.MCP_SERVER_NAME = 'streamby';
+const errorText = (body, status) => {
+    const message = body?.message ?? body?.error;
+    return typeof message === 'string' ? message : `StreamBy answered ${status}`;
+};
+/**
+ * An MCP server for one request of `auth` (an API token's owner): its tools, the writing ones
+ * only for a token with write access. Each tool call goes to the REST API through `api`, and is
+ * recorded in the audit log.
+ */
+function createMcpServer(auth, api, config, version) {
+    const server = new mcp_js_1.McpServer({ name: exports.MCP_SERVER_NAME, version });
+    const canWrite = auth.apiToken?.access === 'write';
+    for (const tool of tools_1.TOOLS) {
+        if (tool.write && !canWrite)
+            continue;
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.input,
+            annotations: { readOnlyHint: !tool.write, destructiveHint: false, openWorldHint: false },
+        }, async (args) => {
+            const started = Date.now();
+            const projectId = tool.projectOf?.(args) ?? null;
+            let status = null;
+            try {
+                const answer = await api(tool.call(args));
+                status = answer.status;
+                const ok = status >= 200 && status < 300;
+                await (0, audit_1.recordMcpCall)({
+                    userId: auth.userId, tokenId: auth.apiToken.tokenId, projectId, tool: tool.name,
+                    ok, status, error: ok ? null : errorText(answer.body, status), durationMs: Date.now() - started,
+                }, config);
+                if (!ok)
+                    return { isError: true, content: [{ type: 'text', text: errorText(answer.body, status) }] };
+                const result = tool.pick ? tool.pick(answer.body, args) : answer.body;
+                return { content: [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }] };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                await (0, audit_1.recordMcpCall)({
+                    userId: auth.userId, tokenId: auth.apiToken.tokenId, projectId, tool: tool.name,
+                    ok: false, status, error: message, durationMs: Date.now() - started,
+                }, config);
+                return { isError: true, content: [{ type: 'text', text: `The call failed: ${message}` }] };
+            }
+        });
+    }
+    return server;
+}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export interface ToolCall {
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT';
+    path: string;
+    body?: unknown;
+}
+export interface ToolDefinition<S extends z.ZodRawShape = z.ZodRawShape> {
+    name: string;
+    title: string;
+    description: string;
+    write: boolean;
+    input: S;
+    projectOf?: (args: z.infer<z.ZodObject<S>>) => string | undefined;
+    call: (args: z.infer<z.ZodObject<S>>) => ToolCall;
+    pick?: (data: any, args: z.infer<z.ZodObject<S>>) => unknown;
+}
+export declare const TOOLS: ToolDefinition<any>[];

package/dist/mcp/tools.js

@@ -0,0 +1,227 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLS = void 0;
+const zod_1 = require("zod");
+const tool = (definition) => definition;
+const id = (what) => zod_1.z.string().min(1).describe(`The ${what}'s id`);
+const projectId = id('project');
+const enc = encodeURIComponent;
+const byProject = ({ projectId }) => projectId;
+const CATEGORIES = ['images', 'audios', 'videos', '3d-models'];
+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"),
+    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"),
+    dueDate: zod_1.z.string().optional().describe('An ISO 8601 date'),
+    notes: zod_1.z.string().optional(),
+};
+const rightsFields = {
+    rightsHolder: zod_1.z.string().optional(),
+    licenseType: zod_1.z.string().optional().describe('e.g. CC0, CC BY 4.0, proprietary'),
+    licenseUrl: zod_1.z.string().optional(),
+    territory: zod_1.z.string().optional(),
+    expiresAt: zod_1.z.string().optional().describe('An ISO 8601 date'),
+    usageRestrictions: zod_1.z.string().optional(),
+    notes: zod_1.z.string().optional(),
+};
+// Only the fields given (an unset optional field isn't sent as undefined).
+const defined = (fields) => Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+exports.TOOLS = [
+    // ── Reading ──
+    tool({
+        name: 'list_projects', title: 'List projects', write: false,
+        description: 'The StreamBy projects this token reaches.',
+        input: {},
+        call: () => ({ method: 'GET', path: '/projects' }),
+        pick: (data) => data.projects,
+    }),
+    tool({
+        name: 'get_project', title: 'Get a project', write: false,
+        description: "A project's details: its name, description, members, exports and connections.",
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}` }),
+    }),
+    tool({
+        name: 'list_assets', title: 'List assets', write: false,
+        description: "A project's assets of a category (images, audios, videos, 3d-models), optionally in one storage connection, and optionally only those whose name contains `query`.",
+        input: {
+            projectId,
+            category: zod_1.z.enum(CATEGORIES),
+            connectionId: zod_1.z.string().optional().describe("A storage connection's id; the project's built-in storage if not given"),
+            query: zod_1.z.string().optional().describe('Only assets whose name contains it (case-insensitive)'),
+        },
+        projectOf: byProject,
+        call: ({ projectId, category, connectionId }) => ({
+            method: 'GET',
+            path: connectionId
+                ? `/projects/${enc(projectId)}/connections/storage/${enc(connectionId)}/files/${category}`
+                : `/projects/${enc(projectId)}/storage/${category}`,
+        }),
+        pick: (data, { query }) => {
+            const files = Array.isArray(data?.data) ? data.data : [];
+            if (!query)
+                return files;
+            const q = query.toLowerCase();
+            return files.filter(f => [f.name, f.displayName, f.originalName, f.fileName]
+                .some(n => typeof n === 'string' && n.toLowerCase().includes(q)));
+        },
+    }),
+    tool({
+        name: 'get_asset_metadata', title: "Get an asset's metadata", write: false,
+        description: "An asset's metadata (technical data and custom tags).",
+        input: { projectId, fileId: id('asset') },
+        projectOf: byProject,
+        call: ({ projectId, fileId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/assets/${enc(fileId)}/metadata` }),
+    }),
+    tool({
+        name: 'get_asset_rights', title: "Get an asset's rights", write: false,
+        description: "An asset's rights: holder, license, territory, expiry and restrictions.",
+        input: { projectId, assetId: id('asset') },
+        projectOf: byProject,
+        call: ({ projectId, assetId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/assets/${enc(assetId)}/rights` }),
+    }),
+    tool({
+        name: 'get_workflow', title: "Get a project's workflow", write: false,
+        description: "A project's workflow (its node graph).",
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/workflow` }),
+    }),
+    tool({
+        name: 'list_pipelines', title: 'List pipelines', write: false,
+        description: "A project's pipelines.",
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/pipelines` }),
+    }),
+    tool({
+        name: 'get_pipeline', title: 'Get a pipeline', write: false,
+        description: 'A pipeline, with its node schema.',
+        input: { projectId, pipelineId: id('pipeline') },
+        projectOf: byProject,
+        call: ({ projectId, pipelineId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/pipelines/${enc(pipelineId)}` }),
+    }),
+    tool({
+        name: 'list_exports', title: 'List exports', write: false,
+        description: "A project's exports (its published endpoints).",
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}` }),
+        pick: (data) => data?.project?.exports ?? data?.exports ?? [],
+    }),
+    tool({
+        name: 'get_export', title: 'Get an export', write: false,
+        description: 'An export, with its node schema.',
+        input: { projectId, exportId: id('export') },
+        projectOf: byProject,
+        call: ({ projectId, exportId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/exports/${enc(exportId)}` }),
+    }),
+    tool({
+        name: 'get_job', title: 'Get a job', write: false,
+        description: "A job's status and progress (transcoding, rendering, ingesting...).",
+        input: { jobId: id('job') },
+        call: ({ jobId }) => ({ method: 'GET', path: `/jobs/${enc(jobId)}` }),
+    }),
+    tool({
+        name: 'list_sequences', title: 'List production sequences', write: false,
+        description: "A project's production sequences.",
+        input: { projectId },
+        projectOf: byProject,
+        call: ({ projectId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/production/sequences` }),
+    }),
+    tool({
+        name: 'list_shots', title: 'List shots', write: false,
+        description: "A production sequence's shots.",
+        input: { projectId, sequenceId: id('sequence') },
+        projectOf: byProject,
+        call: ({ projectId, sequenceId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/production/sequences/${enc(sequenceId)}/shots` }),
+    }),
+    tool({
+        name: 'list_tasks', title: 'List shot tasks', write: false,
+        description: "A shot's tasks.",
+        input: { projectId, shotId: id('shot') },
+        projectOf: byProject,
+        call: ({ projectId, shotId }) => ({ method: 'GET', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}/tasks` }),
+    }),
+    // ── Writing ──
+    tool({
+        name: 'update_asset_metadata', title: "Update an asset's custom tags", write: true,
+        description: "Sets an asset's custom tags (key/value pairs), replacing the ones it had.",
+        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", write: true,
+        description: "Sets an asset's rights: holder, license, territory, expiry, restrictions and notes.",
+        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', write: true,
+        description: 'Creates a pipeline in a project.',
+        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) }),
+    }),
+    tool({
+        name: 'update_pipeline', title: 'Update a pipeline', write: true,
+        description: "Changes a pipeline's name, description or order.",
+        input: { projectId, pipelineId: id('pipeline'), name: zod_1.z.string().min(1).optional(), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
+        projectOf: byProject,
+        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', write: true,
+        description: 'Creates a production sequence in a project.',
+        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) }),
+    }),
+    tool({
+        name: 'update_sequence', title: 'Update a production sequence', write: true,
+        description: "Changes a sequence's name, description or order.",
+        input: { projectId, sequenceId: id('sequence'), name: zod_1.z.string().min(1).optional(), description: zod_1.z.string().optional(), order: zod_1.z.number().optional() },
+        projectOf: byProject,
+        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', write: true,
+        description: 'Creates a shot in a production sequence.',
+        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) }),
+    }),
+    tool({
+        name: 'update_shot', title: 'Update a shot', write: true,
+        description: 'Changes a shot (its name, status, assignee, due date...).',
+        input: { projectId, shotId: id('shot'), name: zod_1.z.string().min(1).optional(), ...shotFields },
+        projectOf: byProject,
+        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', write: true,
+        description: 'Creates a task in a shot.',
+        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) }),
+    }),
+    tool({
+        name: 'update_task', title: 'Update a shot task', write: true,
+        description: 'Changes a task (its name, status, priority, assignee, due date, notes).',
+        input: { projectId, shotId: id('shot'), taskId: id('task'), name: zod_1.z.string().min(1).optional(), ...taskFields },
+        projectOf: byProject,
+        call: ({ projectId, shotId, taskId, ...fields }) => ({ method: 'PATCH', path: `/projects/${enc(projectId)}/production/shots/${enc(shotId)}/tasks/${enc(taskId)}`, body: defined(fields) }),
+    }),
+];

package/dist/middleware/createRouter.js

@@ -13,6 +13,7 @@ const reencryptCredentials_1 = require("../services/reencryptCredentials");
 const wsHub_1 = require("../services/wsHub");
 const auth_1 = require("../services/auth");
 const apiToken_1 = require("./routes/apiToken");
+const mcp_1 = require("./routes/mcp");
 const encryption_1 = require("../utils/encryption");
 const auth_2 = require("./routes/auth");
 const user_1 = require("./routes/user");
@@ -97,6 +98,7 @@ function createStreamByRouter(config) {
             (0, manager_1.registerModel)('user_subscriptions', [mainDb.id], 'user_subscriptions', 'streamby');
             (0, manager_1.registerModel)('user_integrations', [mainDb.id], 'user_integrations', streambySchema);
             (0, manager_1.registerModel)('api_tokens', [mainDb.id], 'api_tokens', streambySchema);
+            (0, manager_1.registerModel)('mcp_audit', [mainDb.id], 'mcp_audit', streambySchema);
         }
     }
     if (config.websocket?.server) {
@@ -110,6 +112,7 @@ function createStreamByRouter(config) {
     router.use(subscription_1.ensureSubscription);
     router.use((0, user_1.userRouter)(config));
     router.use((0, apiToken_1.apiTokenRouter)(config));
+    router.use((0, mcp_1.mcpRouter)(config));
     router.use((0, export_1.exportRouter)(config));
     router.use((0, member_1.memberRouter)(config));
     router.use((0, storage_2.storageRouter)(config));

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

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

package/dist/middleware/routes/mcp.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpRouter = mcpRouter;
+const express_1 = require("express");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const server_1 = require("../../mcp/server");
+const rateLimit_1 = require("../../mcp/rateLimit");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { version } = require('../../../package.json');
+const jsonRpcError = (res, status, message) => res.status(status).json({ jsonrpc: '2.0', error: { code: -32000, message }, id: null });
+// StreamBy's MCP server (Streamable HTTP, stateless: one server per request), for agents
+// working with StreamBy through an API token. Each tool calls the REST API right here -- this
+// same process, under the same mount -- with the request's own Authorization header, so it
+// reaches what the token and its owner can and nothing more.
+function mcpRouter(config) {
+    const router = (0, express_1.Router)();
+    const limiter = (0, rateLimit_1.createRateLimiter)(config.mcp?.rateLimit ?? rateLimit_1.DEFAULT_MCP_RATE_LIMIT);
+    router.post('/mcp', async (req, res) => {
+        const auth = req.auth;
+        if (!auth.apiToken)
+            return jsonRpcError(res, 401, 'The MCP server takes an API token (Authorization: Bearer sbt_...)');
+        const taken = limiter.take(auth.apiToken.tokenId);
+        if (!taken.allowed) {
+            res.setHeader('Retry-After', String(Math.ceil(taken.retryAfterMs / 1000)));
+            return jsonRpcError(res, 429, 'Too many requests for this API token; try again later');
+        }
+        const base = config.mcp?.apiBaseUrl ?? `http://127.0.0.1:${req.socket.localPort}${req.baseUrl}`;
+        const api = async ({ method, path, body }) => {
+            const answer = await fetch(`${base}${path}`, {
+                method,
+                headers: { Authorization: req.headers.authorization ?? '', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                redirect: 'error',
+            });
+            const text = await answer.text();
+            let parsed = null;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                parsed = text;
+            }
+            return { status: answer.status, body: parsed };
+        };
+        const server = (0, server_1.createMcpServer)(auth, api, config, version);
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on('close', () => { transport.close(); server.close(); });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (err) {
+            console.error('❌ StreamBy MCP: request failed:', err instanceof Error ? err.message : err);
+            if (!res.headersSent)
+                jsonRpcError(res, 500, 'Internal error');
+        }
+    });
+    // Stateless: no session to stream to, nor to end.
+    router.get('/mcp', (_req, res) => jsonRpcError(res, 405, 'Method not allowed'));
+    router.delete('/mcp', (_req, res) => jsonRpcError(res, 405, 'Method not allowed'));
+    return router;
+}

package/dist/services/auth.js

@@ -33,6 +33,9 @@ const enforceApiTokenScope = (req, res, next) => {
     const scope = req.auth?.apiToken;
     if (!scope)
         return next();
+    // The MCP server handles a token itself: its tools call the routes here, each one checked.
+    if (req.path === '/mcp')
+        return next();
     if (/^\/user\/api-tokens(\/|$)/.test(req.path)) {
         return res.status(403).json({ error: 'API tokens are managed with a session, not with a token' });
     }

package/dist/types/index.d.ts

@@ -133,6 +133,13 @@ export interface StreamByConfig {
     adapter?: StorageAdapter;
     encrypt?: string;
     encryptPreviousKeys?: string[];
+    mcp?: {
+        rateLimit?: {
+            requests: number;
+            windowMs: number;
+        };
+        apiBaseUrl?: string;
+    };
     websocket?: {
         server: WebSocketServer;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "streamby-core",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "StreamBy middleware framework for media storage management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -32,6 +32,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.528.0",
     "@aws-sdk/s3-request-presigner": "^3.787.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@prisma/client": "^6.12.0",
     "bcrypt": "^5.1.1",
     "dotenv": "^16.5.0",
@@ -41,7 +42,8 @@
     "node-fetch": "^3.0.0",
     "pg": "^8.16.3",
     "prisma": "^6.12.0",
-    "ws": "^8.20.0"
+    "ws": "^8.20.0",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/bcrypt": "^5.0.2",