streamby-core 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # 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
+
+- **API tokens**, so agents and services can work with StreamBy as a user without the user's
+  browser session. The README has the details.
+  - `GET`, `POST` and `DELETE /user/api-tokens` let a user list, make and revoke their own
+    tokens. These routes need a session: a token can't manage tokens.
+  - A token is `sbt_` followed by 32 random bytes. It's shown once, when it's made.
+  - **Scope:** each token is `read` (only reads) or `write` (reads and writes). It reaches a
+    list of projects, or `'*'` for every project its owner is a member of, including ones they
+    join later. It expires in 7, 30, 90 or 365 days, or never.
+  - A request made with a token reaches only its scope:
+    - a `read` token can't write;
+    - a project outside its scope answers 404, and the project list and jobs show only its
+      projects;
+    - outside a project, it can only make a few reads.
+
+    The owner's role in each project still applies on top, so a token never does more than
+    its owner can, and it stops reaching a project once its owner leaves it.
+  - **`resolveApiToken`** (exported, with `API_TOKEN_PREFIX`) is for the host's
+    `authProvider`. It turns `Authorization: Bearer sbt_...` into the token's owner and scope,
+    or `null` once the token is revoked or expired. The `authProvider` returns the scope as
+    `Auth.apiToken`. Without it, a token would have all of its owner's access.
+  - **New table: `api_tokens`.** It's created at startup in the main database, and it keeps
+    only each token's SHA-256 hash, never the token itself.
+
+### Security
+
+- A connection authenticated with an API token can't open the WebSocket. It's closed with
+  code 1008. The WebSocket belongs to the browser session and receives every event of its
+  user, from any project.
+
 ## 0.34.0
 
 ### ⚠️ Migration and deploy

package/README.md

@@ -1,4 +1,4 @@
-# @streamby/core
+# streamby-core
 
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPLv3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
@@ -9,7 +9,7 @@ Part of the [StreamBy](https://streamby.nhexa.cl) ecosystem by TerminalCore Labs
 
 ## 🚀 What is it?
 
-`@streamby/core` is a plug-and-play middleware for Express (or compatible frameworks) that enables file uploads, listings and **multi-project access** over services like:
+`streamby-core` is a plug-and-play middleware for Express (or compatible frameworks) that enables file uploads, listings and **multi-project access** over services like:
 
 - ✅ AWS S3
 - ✅ Google Cloud Storage (soon)
@@ -23,7 +23,7 @@ It's designed to be installed inside your existing API as a library — **no nee
 ## 📦 Installation
 
 ```bash
-npm install @streamby/core ws
+npm install streamby-core ws
 npm install -D @types/ws
 ```
 
@@ -35,7 +35,7 @@ npm install -D @types/ws
 import http from 'http';
 import express from 'express';
 import { WebSocketServer } from 'ws';
-import { createStreamByRouter } from '@streamby/core';
+import { createStreamByRouter } from 'streamby-core';
 
 const app = express();
 const server = http.createServer(app);
@@ -100,6 +100,148 @@ createStreamByRouter({
 
 ---
 
+## 🎫 API tokens
+
+Agents and services work with StreamBy as a user through API tokens, without the user's
+browser session. A user manages their own tokens (`GET`, `POST` and
+`DELETE /streamby/user/api-tokens`, only with a session). Each token has:
+
+- **an access level**: `read` (only reads) or `write` (reads and writes);
+- **the projects it reaches**: a list of project ids, or `'*'` for every project the user is a
+  member of, including ones they join later;
+- **an expiry**: 7, 30, 90 or 365 days, or none.
+
+A token is `sbt_` followed by 32 random bytes. It's shown once, when it's made. Only its
+SHA-256 hash is stored, with a short prefix to tell it apart.
+
+Requests send it as `Authorization: Bearer sbt_...`. Your `authProvider` resolves it with
+`resolveApiToken` and returns its owner, with the token's scope in `apiToken`:
+
+```ts
+import { createStreamByRouter, resolveApiToken, API_TOKEN_PREFIX } from 'streamby-core';
+
+createStreamByRouter({
+  // ...
+  authProvider: async (req) => {
+    const bearer = req.headers.authorization?.replace(/^Bearer /, '');
+    if (bearer?.startsWith(API_TOKEN_PREFIX)) {
+      const resolved = await resolveApiToken(bearer); // null once revoked or expired
+      if (!resolved) throw new Error('Invalid API token');
+      const user = await findUser(resolved.userId);   // your own user lookup
+      return { userId: user.id, username: user.username, role: user.role, apiToken: resolved.scope };
+    }
+    // ...your session-based authentication
+  },
+});
+```
+
+A request made with a token reaches only what the token's scope allows:
+
+- a `read` token can't write;
+- a project outside the token's projects answers 404, and the project list shows only the
+  token's projects;
+- a token can't manage tokens;
+- outside a project, a token can only make a few reads (`/auth`, `/projects`, `/jobs/:jobId`,
+  `/user/subscription`, `/users/search`).
+
+The owner's role in each project still applies on top of that. A token never does more than
+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
@@ -120,7 +262,7 @@ nor one that starts a job.
 
 ## 🗄️ Database Schema Setup
 
-`@streamby/core` requires a pre-configured database schema for its internal operations. It does not manage database connections directly; instead, it expects the host application to provide initialized connection instances. This ensures full control and flexibility for the host environment.
+`streamby-core` requires a pre-configured database schema for its internal operations. It does not manage database connections directly; instead, it expects the host application to provide initialized connection instances. This ensures full control and flexibility for the host environment.
 
 The library will only interact with the specified schema and will not touch other schemas in your database. The `reset` option is opt-in and will only drop and recreate the specified `streamby` schema if explicitly set to `true`.
 
@@ -128,7 +270,7 @@ The library will only interact with the specified schema and will not touch othe
 
 ```ts
 import { Pool } from "pg";
-import { setupStreambyPg } from "@streamby/core/pg/setup"; // Adjust path as per your package structure
+import { setupStreambyPg } from "streamby-core/pg/setup"; // Adjust path as per your package structure
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
 
@@ -141,7 +283,7 @@ await setupStreambyPg({ pool, schema: "streamby", reset: false });
 
 ```ts
 import { MongoClient } from "mongodb";
-import { setupStreambyMongo } from "@streamby/core/mongo/setup"; // Adjust path as per your package structure
+import { setupStreambyMongo } from "streamby-core/mongo/setup"; // Adjust path as per your package structure
 
 const client = new MongoClient(process.env.MONGO_URL!);
 
@@ -154,7 +296,7 @@ await setupStreambyMongo({ client, dbName: "streamby" });
 
 ```ts
 import express from 'express';
-import { createStreamByRouter } from '@streamby/core';
+import { createStreamByRouter } from 'streamby-core';
 
 const app = express();
 
@@ -215,7 +357,7 @@ Unit tests use [Vitest](https://vitest.dev) and [Supertest](https://www.npmjs.co
 
 ## 🗺️ API Endpoints
 
-Here's a summary of the key API endpoints provided by `@streamby/core`:
+Here's a summary of the key API endpoints provided by `streamby-core`:
 
 ### `GET /streamby/projects`
 
@@ -330,5 +472,5 @@ Copyright (C) 2026 TerminalCore Labs
 
 Licensed under the [GNU Affero General Public License v3.0](./LICENSE) (AGPL-3.0-only).
 
-> **Note for consumers:** unlike most installable packages, this one is intentionally AGPL rather than MIT. AGPL's copyleft applies to any project that depends on it -- if you install `@streamby/core`, your own project must also be licensed under AGPL-3.0 (or a compatible copyleft license). Confirm this is acceptable for your use case before adding this dependency.
+> **Note for consumers:** unlike most installable packages, this one is intentionally AGPL rather than MIT. AGPL's copyleft applies to any project that depends on it -- if you install `streamby-core`, your own project must also be licensed under AGPL-3.0 (or a compatible copyleft license). Confirm this is acceptable for your use case before adding this dependency.
 

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(`
@@ -147,6 +148,41 @@ const ensureTablesExist = async (pool) => {
       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.
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS streamby.api_tokens (
+        id            TEXT PRIMARY KEY DEFAULT uuid_generate_v4()::text,
+        "userId"      VARCHAR(255) NOT NULL,
+        name          VARCHAR(255) NOT NULL,
+        prefix        VARCHAR(32) NOT NULL,
+        hash          CHAR(64) NOT NULL UNIQUE,
+        access        VARCHAR(10) NOT NULL,
+        "projectIds"  JSONB NOT NULL,
+        "createdAt"   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+        "expiresAt"   TIMESTAMP WITH TIME ZONE,
+        "lastUsedAt"  TIMESTAMP WITH TIME ZONE
+      );
+      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/index.d.ts

@@ -1,4 +1,6 @@
 export { createStreamByRouter } from './middleware/createRouter';
 export { emitToUser } from './services/wsHub';
 export { createNotification } from './services/notification';
-export type { UserPlan, UserSubscription } from './types';
+export type { UserPlan, UserSubscription, Auth, ApiTokenScope, ApiTokenAccess } from './types';
+export { resolveApiToken, API_TOKEN_PREFIX } from './services/apiTokens';
+export type { ResolvedApiToken } from './services/apiTokens';

package/dist/index.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
+exports.API_TOKEN_PREFIX = exports.resolveApiToken = exports.createNotification = exports.emitToUser = exports.createStreamByRouter = void 0;
 var createRouter_1 = require("./middleware/createRouter");
 Object.defineProperty(exports, "createStreamByRouter", { enumerable: true, get: function () { return createRouter_1.createStreamByRouter; } });
 var wsHub_1 = require("./services/wsHub");
 Object.defineProperty(exports, "emitToUser", { enumerable: true, get: function () { return wsHub_1.emitToUser; } });
 var notification_1 = require("./services/notification");
 Object.defineProperty(exports, "createNotification", { enumerable: true, get: function () { return notification_1.createNotification; } });
+var apiTokens_1 = require("./services/apiTokens");
+Object.defineProperty(exports, "resolveApiToken", { enumerable: true, get: function () { return apiTokens_1.resolveApiToken; } });
+Object.defineProperty(exports, "API_TOKEN_PREFIX", { enumerable: true, get: function () { return apiTokens_1.API_TOKEN_PREFIX; } });

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

@@ -12,6 +12,8 @@ const backfillBuiltinConnections_1 = require("../services/backfillBuiltinConnect
 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");
@@ -95,6 +97,8 @@ function createStreamByRouter(config) {
             (0, manager_1.registerModel)('users', [mainDb.id], 'users', 'accounts');
             (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) {
@@ -104,8 +108,11 @@ function createStreamByRouter(config) {
     // but for the public export route (see authenticate).
     router.use((0, auth_2.authRouter)(config));
     router.use((0, auth_1.authenticate)(config));
+    router.use(auth_1.enforceApiTokenScope);
     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/apiToken.d.ts

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

package/dist/middleware/routes/apiToken.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiTokenRouter = apiTokenRouter;
+const express_1 = require("express");
+const manager_1 = require("../../models/manager");
+const auth_1 = require("../../utils/auth");
+const apiTokens_1 = require("../../services/apiTokens");
+// The signed-in user's own API tokens (see services/apiTokens): listed, made, revoked. Only
+// with a session: a token can't manage tokens (see enforceApiTokenScope).
+function apiTokenRouter(config) {
+    const router = (0, express_1.Router)();
+    const Project = (0, manager_1.getModel)('projects');
+    router.get('/user/api-tokens', async (req, res) => {
+        try {
+            const auth = req.auth;
+            res.json({ apiTokens: await (0, apiTokens_1.listApiTokens)(auth.userId) });
+        }
+        catch (err) {
+            res.status(500).json({ message: 'Failed to list API tokens', details: err.message });
+        }
+    });
+    // The token itself is in this response only: it's never stored, nor shown again.
+    router.post('/user/api-tokens', async (req, res) => {
+        try {
+            const auth = req.auth;
+            const { name, access, projectIds, expiresInDays } = req.body ?? {};
+            // A token reaches only projects its owner is in.
+            if (Array.isArray(projectIds)) {
+                for (const id of projectIds) {
+                    const project = typeof id === 'string' ? await Project.findOne({ _id: id }) : null;
+                    if (!(0, auth_1.isProjectMember)(project, auth.userId)) {
+                        return res.status(400).json({ message: `You are not a member of project '${id}'` });
+                    }
+                }
+            }
+            const { token, info } = await (0, apiTokens_1.createApiToken)(auth.userId, { name, access, projectIds, expiresInDays: expiresInDays ?? null }, config);
+            res.status(201).json({ token, apiToken: info, message: 'Copy the token now: it will not be shown again' });
+        }
+        catch (err) {
+            if (err instanceof apiTokens_1.ApiTokenError)
+                return res.status(err.status).json({ message: err.message });
+            res.status(500).json({ message: 'Failed to create API token', details: err.message });
+        }
+    });
+    router.delete('/user/api-tokens/:tokenId', async (req, res) => {
+        try {
+            const auth = req.auth;
+            const revoked = await (0, apiTokens_1.revokeApiToken)(auth.userId, req.params.tokenId);
+            if (!revoked)
+                return res.status(404).json({ message: 'API token not found' });
+            res.status(204).end();
+        }
+        catch (err) {
+            res.status(500).json({ message: 'Failed to revoke API token', details: err.message });
+        }
+    });
+    return router;
+}

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/middleware/routes/media.js

@@ -8,6 +8,7 @@ const jobQueue_1 = require("../../services/jobQueue");
 const mediaProcessor_1 = require("../../services/mediaProcessor");
 const storage_1 = require("../../providers/storage");
 const connectionManager_1 = require("../../adapters/database/connectionManager");
+const auth_2 = require("../../services/auth");
 function getMetadataCollection() {
     const ids = (0, connectionManager_1.getConnectedIds)().filter(id => (0, connectionManager_1.getConnection)(id).type === 'nosql');
     if (!ids.length)
@@ -33,6 +34,9 @@ function mediaRouter(config) {
             const job = (0, jobQueue_1.getJob)(req.params.jobId);
             if (!job)
                 return res.status(404).json({ message: 'Job not found' });
+            // With an API token, only a job of a project it reaches.
+            if (!(0, auth_2.scopeReachesProject)(auth.apiToken, job.projectId))
+                return res.status(404).json({ message: 'Job not found' });
             if (job.userId !== auth.userId) {
                 const project = await Project.findOne({ _id: job.projectId });
                 if (!(0, auth_1.isProjectMember)(project, auth.userId))

package/dist/middleware/routes/project.js

@@ -8,6 +8,7 @@ const connectionManager_1 = require("../../adapters/database/connectionManager")
 const sql_1 = require("../../adapters/database/sql");
 const sanitize_1 = require("../../utils/sanitize");
 const projectIntegration_1 = require("../../services/projectIntegration");
+const auth_2 = require("../../services/auth");
 function projectRouter(config) {
     const router = (0, express_1.Router)();
     const Project = (0, manager_1.getModel)('projects');
@@ -32,6 +33,9 @@ function projectRouter(config) {
                 const currentUserMember = project.members?.find((m) => m.userId?.toString() === auth.userId?.toString());
                 if (!currentUserMember || currentUserMember.status !== 'active')
                     return false;
+                // With an API token, only the projects it reaches.
+                if (!(0, auth_2.scopeReachesProject)(auth.apiToken, (project._id ?? project.id)?.toString()))
+                    return false;
                 if (filterArchived !== undefined) {
                     return (currentUserMember.archived || false) === filterArchived;
                 }

package/dist/services/apiTokens.d.ts

@@ -0,0 +1,47 @@
+import { ApiTokenAccess, ApiTokenScope, StreamByConfig } from '../types';
+export declare const API_TOKEN_PREFIX = "sbt_";
+export declare const API_TOKEN_EXPIRY_DAYS: readonly [7, 30, 90, 365];
+export interface ApiTokenRecord {
+    id: string;
+    userId: string;
+    name: string;
+    prefix: string;
+    hash: string;
+    access: ApiTokenAccess;
+    projectIds: string[];
+    createdAt: Date;
+    expiresAt: Date | null;
+    lastUsedAt: Date | null;
+}
+/** What a token's owner sees of it. */
+export type ApiTokenInfo = Omit<ApiTokenRecord, 'hash' | 'userId' | 'projectIds'> & {
+    projectIds: string[] | '*';
+};
+export declare class ApiTokenError extends Error {
+    status: number;
+    constructor(message: string, status?: number);
+}
+export interface CreateApiTokenInput {
+    name: string;
+    access: ApiTokenAccess;
+    projectIds: string[] | '*';
+    expiresInDays: number | null;
+}
+/** A new token for `userId`: the token itself, shown only now, and what's kept of it. */
+export declare function createApiToken(userId: string, input: CreateApiTokenInput, config: StreamByConfig): Promise<{
+    token: string;
+    info: ApiTokenInfo;
+}>;
+/** The tokens `userId` has. */
+export declare function listApiTokens(userId: string): Promise<ApiTokenInfo[]>;
+/** Revokes one of `userId`'s tokens: it stops working at once. Whether there was one. */
+export declare function revokeApiToken(userId: string, tokenId: string): Promise<boolean>;
+export interface ResolvedApiToken {
+    userId: string;
+    scope: ApiTokenScope;
+}
+/**
+ * The token's owner and scope, for the host's authProvider; null when it isn't a token, isn't
+ * known (revoked), or has expired. Marks when it was last used.
+ */
+export declare function resolveApiToken(token: unknown): Promise<ResolvedApiToken | null>;

package/dist/services/apiTokens.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiTokenError = exports.API_TOKEN_EXPIRY_DAYS = exports.API_TOKEN_PREFIX = void 0;
+exports.createApiToken = createApiToken;
+exports.listApiTokens = listApiTokens;
+exports.revokeApiToken = revokeApiToken;
+exports.resolveApiToken = resolveApiToken;
+const crypto_1 = __importDefault(require("crypto"));
+const manager_1 = require("../models/manager");
+// API tokens: how an agent or a service works with StreamBy as a user, without their browser
+// session. A token is "sbt_" and 32 random bytes; only its hash is stored, with a prefix to
+// tell it apart in a list. It's sent as `Authorization: Bearer sbt_...` and the host's
+// authProvider resolves it (resolveApiToken), so the request is its owner's -- limited by the
+// token's scope (read or write, which projects), and never more than its owner can do: the
+// owner's role in each project still decides.
+exports.API_TOKEN_PREFIX = 'sbt_';
+const PREFIX_SHOWN = exports.API_TOKEN_PREFIX.length + 8;
+exports.API_TOKEN_EXPIRY_DAYS = [7, 30, 90, 365];
+const ALL_PROJECTS = '*';
+class ApiTokenError extends Error {
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+exports.ApiTokenError = ApiTokenError;
+const hashOf = (token) => crypto_1.default.createHash('sha256').update(token).digest('hex');
+const infoOf = ({ hash: _hash, userId: _userId, ...info }) => ({
+    ...info,
+    projectIds: parseProjectIds(info.projectIds),
+});
+// As stored (a list, read back from SQL JSON as a list or its text): ['*'] is every project.
+const parseProjectIds = (value) => {
+    if (typeof value === 'string') {
+        try {
+            return parseProjectIds(JSON.parse(value));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(value))
+        return [];
+    const ids = value.map(String);
+    return ids.includes(ALL_PROJECTS) ? '*' : ids;
+};
+const mainDbType = (config) => config.databases?.find(db => db.main)?.type ?? 'nosql';
+/** A new token for `userId`: the token itself, shown only now, and what's kept of it. */
+async function createApiToken(userId, input, config) {
+    const name = typeof input.name === 'string' ? input.name.trim() : '';
+    if (!name)
+        throw new ApiTokenError('A token needs a name.');
+    if (input.access !== 'read' && input.access !== 'write')
+        throw new ApiTokenError("access must be 'read' or 'write'.");
+    if (input.projectIds !== '*' && (!Array.isArray(input.projectIds) || !input.projectIds.length || !input.projectIds.every(id => typeof id === 'string' && id && id !== ALL_PROJECTS))) {
+        throw new ApiTokenError("projectIds must be '*' or a list of project ids.");
+    }
+    if (input.expiresInDays !== null && !exports.API_TOKEN_EXPIRY_DAYS.includes(input.expiresInDays)) {
+        throw new ApiTokenError(`expiresInDays must be one of ${exports.API_TOKEN_EXPIRY_DAYS.join(', ')}, or null.`);
+    }
+    const token = exports.API_TOKEN_PREFIX + crypto_1.default.randomBytes(32).toString('base64url');
+    const now = new Date();
+    const record = {
+        id: crypto_1.default.randomUUID(),
+        userId,
+        name,
+        prefix: token.slice(0, PREFIX_SHOWN),
+        hash: hashOf(token),
+        access: input.access,
+        projectIds: input.projectIds === '*' ? [ALL_PROJECTS] : [...new Set(input.projectIds)],
+        createdAt: now,
+        expiresAt: input.expiresInDays === null ? null : new Date(now.getTime() + input.expiresInDays * 86400000),
+        lastUsedAt: null,
+    };
+    await (0, manager_1.getModel)('api_tokens').create({ ...record, dbType: mainDbType(config) });
+    return { token, info: infoOf(record) };
+}
+/** The tokens `userId` has. */
+async function listApiTokens(userId) {
+    const records = (await (0, manager_1.getModel)('api_tokens').find({ userId }));
+    return records
+        .map(infoOf)
+        .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+}
+/** Revokes one of `userId`'s tokens: it stops working at once. Whether there was one. */
+async function revokeApiToken(userId, tokenId) {
+    return (await (0, manager_1.getModel)('api_tokens').delete({ id: tokenId, userId })) > 0;
+}
+/**
+ * The token's owner and scope, for the host's authProvider; null when it isn't a token, isn't
+ * known (revoked), or has expired. Marks when it was last used.
+ */
+async function resolveApiToken(token) {
+    if (typeof token !== 'string' || !token.startsWith(exports.API_TOKEN_PREFIX))
+        return null;
+    const ApiTokens = (0, manager_1.getModel)('api_tokens');
+    const record = (await ApiTokens.findOne({ hash: hashOf(token) }));
+    if (!record)
+        return null;
+    if (record.expiresAt && new Date(record.expiresAt).getTime() <= Date.now())
+        return null;
+    ApiTokens.update({ id: record.id }, { lastUsedAt: new Date() }).catch(() => { });
+    return {
+        userId: record.userId,
+        scope: { tokenId: record.id, access: record.access, projectIds: parseProjectIds(record.projectIds) },
+    };
+}

package/dist/services/auth.d.ts

@@ -1,4 +1,7 @@
 import { Request, Response, NextFunction } from 'express';
-import { StreamByConfig } from '../types';
+import { Auth, StreamByConfig } from '../types';
 export declare const isPublicRoute: (method: string, path: string) => boolean;
+/** Whether a token's scope reaches a project. */
+export declare const scopeReachesProject: (scope: Auth["apiToken"], projectId: string) => boolean;
+export declare const enforceApiTokenScope: (req: Request, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
 export declare const authenticate: (config: StreamByConfig) => (req: Request, res: Response, next: NextFunction) => Promise<void | Response<any, Record<string, any>>>;

package/dist/services/auth.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.authenticate = exports.isPublicRoute = void 0;
+exports.authenticate = exports.enforceApiTokenScope = exports.scopeReachesProject = exports.isPublicRoute = void 0;
 // The one route open without a session: a project's public export, read
 // (GET /:projectId/export/:exportName, see routes/export). Exactly that path -- not any path
 // that has an "export" segment somewhere.
@@ -8,6 +8,49 @@ const PUBLIC_EXPORT = /^\/[^/]+\/export\/[^/]+\/?$/;
 const READ_METHODS = ['GET', 'HEAD', 'OPTIONS'];
 const isPublicRoute = (method, path) => READ_METHODS.includes(method.toUpperCase()) && PUBLIC_EXPORT.test(path);
 exports.isPublicRoute = isPublicRoute;
+// ── API tokens ──
+// A request made with an API token reaches only what the token's scope does: no writes with a
+// read token, no project outside its projects (as if it didn't exist), no managing tokens, and
+// of the routes outside a project only the few below. Its owner's role in each project still
+// decides on top (the routes' own checks).
+// The project a route acts on, by its path.
+const PROJECT_PATHS = [/^\/projects\/([^/]+)/, /^\/(?:upload|delete)-project-image-url\/([^/]+)/];
+const NOT_A_PROJECT = new Set(['create', 'explore']);
+const projectIdOf = (path) => {
+    for (const pattern of PROJECT_PATHS) {
+        const id = pattern.exec(path)?.[1];
+        if (id && !NOT_A_PROJECT.has(id))
+            return decodeURIComponent(id);
+    }
+    return undefined;
+};
+// Outside a project, a token reaches only these reads (each limited to its scope there).
+const OUTSIDE_A_PROJECT = [/^\/auth\/?$/, /^\/projects\/?$/, /^\/jobs\/[^/]+\/?$/, /^\/user\/subscription\/?$/, /^\/users\/search\/?$/];
+/** Whether a token's scope reaches a project. */
+const scopeReachesProject = (scope, projectId) => !scope || scope.projectIds === '*' || scope.projectIds.includes(projectId);
+exports.scopeReachesProject = scopeReachesProject;
+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' });
+    }
+    if (!READ_METHODS.includes(req.method.toUpperCase()) && scope.access !== 'write') {
+        return res.status(403).json({ error: 'This API token can only read' });
+    }
+    const projectId = projectIdOf(req.path);
+    if (projectId) {
+        return (0, exports.scopeReachesProject)(scope, projectId) ? next() : res.status(404).json({ message: 'Project not found' });
+    }
+    if (READ_METHODS.includes(req.method.toUpperCase()) && OUTSIDE_A_PROJECT.some(route => route.test(req.path)))
+        return next();
+    return res.status(403).json({ error: 'Not available with an API token' });
+};
+exports.enforceApiTokenScope = enforceApiTokenScope;
 const authenticate = (config) => async (req, res, next) => {
     if ((0, exports.isPublicRoute)(req.method, req.path)) {
         return next();

package/dist/services/wsHub.js

@@ -15,6 +15,12 @@ function initWsHub(wss, config) {
                 ws.close(1008, 'Unauthorized');
                 return;
             }
+            // The WebSocket is the browser session's: it gets every event of its user, whatever the
+            // project, so an API token (scoped to some projects, maybe read-only) never opens it.
+            if (auth.apiToken) {
+                ws.close(1008, "API tokens can't open the WebSocket");
+                return;
+            }
             userId = auth.userId;
         }
         catch (err) {

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;
     };
@@ -158,6 +165,13 @@ export interface Auth {
     userId: string;
     username: string;
     role: 'viewer' | 'editor' | 'admin';
+    apiToken?: ApiTokenScope;
+}
+export type ApiTokenAccess = 'read' | 'write';
+export interface ApiTokenScope {
+    tokenId: string;
+    access: ApiTokenAccess;
+    projectIds: string[] | '*';
 }
 export type AuthProvider = (req: Request) => Promise<Auth>;
 export type UserPlan = 'freemium' | 'subscriber' | 'admin';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "streamby-core",
-  "version": "0.34.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",