@sync.so/mcp-server 0.1.3 → 0.2.0

package/dist/tools/organizations.js

@@ -0,0 +1,235 @@
+import { z } from 'zod';
+import { ApiRequestError } from '../http-client.js';
+import { currentOrganizationSession, ORGANIZATION_HEADER, OrganizationSession, } from '../organization-selection.js';
+/** GET route listing the caller's organizations (sync-api-v2, CRAFT-7789). */
+export const ORGANIZATIONS_PATH = '/v2/account/organizations';
+const SWITCH_HINT = 'Call organizations_list to see the organizations this connection can act in, then organizations_select with an id to switch this session, or pass organizationId on a single paid create (and its estimate) to run only that call there. A Sync app connection (OAuth) acts only in the organizations ticked when it was connected; to add one, the user reconnects Sync and ticks it.';
+const API_KEY_HINT = 'This connection uses an API key, and API keys are bound to the organization that created them. To work in another organization, use an API key created in it, or sign in to Sync instead of using SYNC_API_KEY.';
+const REFUSED_STEP = 'The session keeps its current organization. Pick an id returned by organizations_list and explain the message to the user; do not retry the same id.';
+// Refusals of x-sync-organization-id (sync-api-v2 #7863). The request never fell back to
+// another organization, so nothing ran.
+const ORGANIZATION_REFUSALS = {
+    organization_access_denied: 'Use an organization id from organizations_list, or omit organizationId to use the current one.',
+    oauth_organization_not_granted: 'To add it, reconnect the app and tick that organization on the consent screen, keeping the others you still want. Until then, use an organization from organizations_list.',
+    api_key_organization_bound: "Omit organizationId, or use an API key created in the other organization's Studio settings.",
+    invalid_organization_id: 'Send one organization id from organizations_list.',
+};
+/**
+ * Next step for a refused organization: the API's own suggestion (for a connection without
+ * a grant, reconnecting and ticking that organization), then what not to do.
+ */
+export function organizationNextStep(error) {
+    const fallback = error.code ? ORGANIZATION_REFUSALS[error.code] : undefined;
+    if (!fallback)
+        return undefined;
+    const suggestion = error.suggestion
+        ? `${error.suggestion} Here, organizations_list lists the organizations this connection can use.`
+        : fallback;
+    return `${suggestion} Tell the user; retrying the same organization fails the same way.`;
+}
+export function switchHint(credential) {
+    return credential === 'api_key' ? API_KEY_HINT : SWITCH_HINT;
+}
+const planSchema = z.object({ id: z.string(), name: z.string() });
+const generationLimitsSchema = z.object({
+    concurrency: z.number().finite().nonnegative(),
+    maxOutputDurationSeconds: z.number().finite().nonnegative(),
+});
+const accountOrganizationSchema = z.object({
+    id: z.uuid(),
+    name: z.string().nullable(),
+    role: z.string().optional(),
+});
+export const featuresSchema = z
+    .array(z.string())
+    .describe('Feature flags enabled for this organization. Tools that depend on a flag follow the active organization.');
+/** GET /v2/account `features`: the flag names enabled for this credential, sorted. */
+function enabledFeatures(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((item) => typeof item === 'string').sort();
+}
+/** GET /v2/account, read field by field so one unexpected field never hides the rest. */
+export function parseAccountOverview(value) {
+    const record = value && typeof value === 'object' ? value : {};
+    const organization = accountOrganizationSchema.safeParse(record.organization).data;
+    const plan = planSchema.safeParse(record.plan).data;
+    const limits = generationLimitsSchema.safeParse(record.limits).data;
+    const features = enabledFeatures(record.features);
+    return {
+        ...(organization ? { organization } : {}),
+        ...(typeof record.credentialType === 'string' ? { credentialType: record.credentialType } : {}),
+        ...(plan ? { plan } : {}),
+        ...(limits ? { limits } : {}),
+        ...(features ? { features } : {}),
+    };
+}
+async function readAccount(http, signal, organizationId) {
+    return parseAccountOverview(await http.request('get', '/v2/account', {
+        signal,
+        ...(organizationId ? { headers: { [ORGANIZATION_HEADER]: organizationId } } : {}),
+    }));
+}
+export function sessionOf() {
+    return currentOrganizationSession() ?? new OrganizationSession();
+}
+export function summary(organization) {
+    return { id: organization.id, name: organization.name };
+}
+function describe(organization) {
+    if (!organization)
+        return 'an unknown organization';
+    return organization.name ? `${organization.name} (${organization.id})` : organization.id;
+}
+/** The credential's own organization, read once a minute at most. */
+export async function defaultOrganization(http, session, signal) {
+    const cached = session.defaultOrganization();
+    if (cached)
+        return cached;
+    const account = await readAccount(http, signal);
+    if (!account.organization)
+        throw new Error('Sync did not report the active organization.');
+    const organization = summary(account.organization);
+    session.rememberDefault(organization);
+    return organization;
+}
+export function apiKeyBound(organization) {
+    return new Error(`API keys are bound to one organization, and this key belongs to ${describe(organization)}. ${API_KEY_HINT}`);
+}
+/** Reads the account as `organizationId`; refuses unless the API answered for that organization. */
+export async function readAccountAs(http, organizationId, signal) {
+    let account;
+    try {
+        account = await readAccount(http, signal, organizationId);
+    }
+    catch (error) {
+        if (error instanceof ApiRequestError && error.status !== 401)
+            error.nextStep = organizationNextStep(error) ?? REFUSED_STEP;
+        throw error;
+    }
+    if (account.organization?.id !== organizationId)
+        throw new Error(`Sync did not switch to organization ${organizationId}: the API answered for ${describe(account.organization)}, so this connection cannot choose an organization per request yet. Nothing was changed.`);
+    return { ...account, organization: account.organization };
+}
+const organizationListItem = z.object({
+    id: z.uuid(),
+    name: z.string().nullable(),
+    role: z.string(),
+    plan: planSchema.optional(),
+    isCurrent: z.boolean(),
+});
+// GET /v2/account/organizations: what the credential can act in, current one first.
+const organizationsResponse = z.object({ organizations: z.array(organizationListItem) });
+export const organizationSummarySchema = z.object({ id: z.uuid(), name: z.string().nullable() });
+const listOutput = {
+    organizations: z.array(organizationListItem),
+    current: organizationSummarySchema
+        .nullable()
+        .describe('The organization tools in this session run in.'),
+    selectedBy: z
+        .enum(['session', 'credential'])
+        .describe('session: chosen with organizations_select. credential: the default of this sign-in or API key.'),
+    howToSwitch: z.string(),
+};
+const selectOutput = {
+    organization: accountOrganizationSchema,
+    previousOrganization: organizationSummarySchema.nullable(),
+    changed: z.boolean(),
+    plan: planSchema.optional(),
+    generationLimits: generationLimitsSchema
+        .optional()
+        .describe('Generations that can run at once and the longest output, in seconds.'),
+    features: featuresSchema.optional(),
+    howToSwitch: z.string(),
+};
+function sameFeatures(left, right) {
+    if ((left === undefined) !== (right === undefined))
+        return false;
+    return (left ?? []).join('\n') === (right ?? []).join('\n');
+}
+function selection(account, previous, howToSwitch) {
+    return {
+        organization: account.organization,
+        previousOrganization: previous ?? null,
+        changed: previous?.id !== account.organization.id,
+        ...(account.plan ? { plan: account.plan } : {}),
+        ...(account.limits ? { generationLimits: account.limits } : {}),
+        ...(account.features ? { features: account.features } : {}),
+        howToSwitch,
+    };
+}
+/** API keys cannot switch; selecting the key's own organization only reports it. */
+async function selectWithApiKey(http, session, organizationId, signal) {
+    const stamp = session.featureStamp();
+    const account = await readAccount(http, signal);
+    if (!account.organization || account.organization.id !== organizationId)
+        throw apiKeyBound(account.organization && summary(account.organization));
+    session.recordFeatures(account.features, stamp, account.organization.id);
+    return selection({ ...account, organization: account.organization }, summary(account.organization), API_KEY_HINT);
+}
+export function createOrganizationTools(http, credential) {
+    return [
+        {
+            name: 'organizations_list',
+            title: 'List your Sync organizations',
+            description: 'List the Sync organizations this connection can act in, with role and plan, marking the one this session runs in (isCurrent). Use it when the user names an organization or team, or asks where work is created, then switch with organizations_select or pass organizationId on one paid create. A Sync app connection lists the organizations ticked when it was connected; to add another, the user reconnects Sync and ticks it. With an API key, lists only the key’s organization.',
+            inputSchema: {},
+            outputSchema: listOutput,
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            handler: async (_args, context) => {
+                const session = sessionOf();
+                // An API key lists only its own organization; it never sends the header.
+                const selected = session.selected;
+                const organizations = organizationsResponse
+                    .parse(await http.request('get', ORGANIZATIONS_PATH, { signal: context?.signal }))
+                    .organizations.map((organization) => ({
+                    ...organization,
+                    isCurrent: selected ? organization.id === selected.id : organization.isCurrent,
+                }));
+                const current = organizations.find((organization) => organization.isCurrent);
+                if (current && !selected)
+                    session.rememberDefault(summary(current));
+                return {
+                    organizations,
+                    current: current ? summary(current) : null,
+                    selectedBy: selected ? 'session' : 'credential',
+                    howToSwitch: switchHint(credential),
+                };
+            },
+        },
+        {
+            name: 'organizations_select',
+            title: 'Switch the Sync organization',
+            description: 'Switch this session to another Sync organization the user belongs to; every later call runs there, including paid generations, until the session ends or another switch. Use an id from organizations_list, and only when the user asks to work in that organization. Returns the new organization’s plan, generation limits and feature flags. The API checks access: a Sync app connection can switch only to organizations ticked when it was connected, and otherwise says to reconnect and tick it; API keys are bound to one organization and cannot switch. To run a single generation elsewhere, pass organizationId on that create instead.',
+            inputSchema: {
+                organizationId: z.uuid().describe('Organization id returned by organizations_list.'),
+            },
+            outputSchema: selectOutput,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            handler: async (args, context) => {
+                const organizationId = z.uuid().parse(args.organizationId);
+                const session = sessionOf();
+                if (credential === 'api_key')
+                    return selectWithApiKey(http, session, organizationId, context?.signal);
+                const previous = session.selected ?? session.defaultOrganization();
+                const account = await readAccountAs(http, organizationId, context?.signal);
+                const previousFeatures = session.activeFeatures();
+                session.select(summary(account.organization), account.features);
+                // Tools that depend on a feature flag follow the organization; let the client re-list.
+                if (previous?.id !== organizationId || !sameFeatures(previousFeatures, account.features))
+                    context?.toolListChanged?.();
+                return selection(account, previous, SWITCH_HINT);
+            },
+        },
+    ];
+}

package/dist/tools/output-schemas.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const generationOutputSchema: {
+    id: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    outputMediaUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    outputUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    generationEstimate: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    outputDuration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    error: z.ZodOptional<z.ZodUnknown>;
+    errorCode: z.ZodOptional<z.ZodUnknown>;
+};
+/**
+ * GET /v2/generations/{id} answers with the API's GenerationDto, whose names differ from
+ * the Generation that /v2/generate returns. Keep the shared names, add the DTO's own.
+ */
+export declare const generationDtoOutputSchema: {
+    id: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodOptional<z.ZodString>;
+    outputMediaUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    outputUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    generationEstimate: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    error: z.ZodOptional<z.ZodUnknown>;
+    errorCode: z.ZodOptional<z.ZodUnknown>;
+    model: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    modelName: z.ZodOptional<z.ZodString>;
+    outputMediaLength: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    outputDuration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    potentialError: z.ZodOptional<z.ZodUnknown>;
+};
+export declare const uploadMediaOutputSchema: {
+    assetId: z.ZodString;
+    mediaType: z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+        video: "video";
+    }>;
+    assetType: z.ZodEnum<{
+        AUDIO: "AUDIO";
+        IMAGE: "IMAGE";
+        VIDEO: "VIDEO";
+    }>;
+    input: z.ZodObject<{
+        type: z.ZodEnum<{
+            audio: "audio";
+            image: "image";
+            video: "video";
+        }>;
+        assetId: z.ZodString;
+    }, z.core.$strip>;
+};
+//# sourceMappingURL=output-schemas.d.ts.map

package/dist/tools/output-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-schemas.d.ts","sourceRoot":"","sources":["../../src/tools/output-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,sBAAsB;IACjC,EAAE;IACF,SAAS;IACT,MAAM;IACN,KAAK;IACL,cAAc;IACd,SAAS;IAMT,kBAAkB;IAOlB,cAAc;IACd,KAAK;IACL,SAAS;CACV,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;CAerC,CAAC;AAEF,eAAO,MAAM,uBAAuB;IAClC,OAAO;IACP,SAAS;;;;;IACT,SAAS;;;;;IACT,KAAK;;;;;;;;CAMN,CAAC"}

package/dist/tools/output-schemas.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+const resultUrl = z
+    .string()
+    .nullable()
+    .describe('Signed result URL when the generation is complete, named as in the API (GET /v2/generations/{id}). Copy this exact string verbatim; do not reconstruct, shorten, or edit it.')
+    .optional();
+export const generationOutputSchema = {
+    id: z.string().describe('Sync generation id.').optional(),
+    projectId: z.string().nullable().describe('Sync project containing this generation.').optional(),
+    status: z.string().describe('Current generation status.').optional(),
+    model: z.string().describe('Model used for the generation.').optional(),
+    outputMediaUrl: resultUrl,
+    outputUrl: z
+        .string()
+        .nullable()
+        .describe('Deprecated alias of outputMediaUrl, with the same value. Read outputMediaUrl.')
+        .meta({ deprecated: true })
+        .optional(),
+    generationEstimate: z
+        .record(z.string(), z.unknown())
+        .nullable()
+        .optional()
+        .describe('Server-provided completion estimate and server clock. Use only for approximate remaining time; do not invent an estimate when absent.'),
+    outputDuration: z.number().nullable().describe('Output duration in seconds.').optional(),
+    error: z.unknown().optional(),
+    errorCode: z.unknown().optional(),
+};
+/**
+ * GET /v2/generations/{id} answers with the API's GenerationDto, whose names differ from
+ * the Generation that /v2/generate returns. Keep the shared names, add the DTO's own.
+ */
+export const generationDtoOutputSchema = {
+    ...generationOutputSchema,
+    model: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .describe('Model used for the generation.')
+        .optional(),
+    modelName: z.string().describe('Name of the model used for the generation.').optional(),
+    outputMediaLength: z.number().nullable().describe('Output duration in seconds.').optional(),
+    outputDuration: z
+        .number()
+        .nullable()
+        .describe('Deprecated alias of outputMediaLength, with the same value.')
+        .meta({ deprecated: true })
+        .optional(),
+    potentialError: z.unknown().optional(),
+};
+export const uploadMediaOutputSchema = {
+    assetId: z.string().describe('Durable Sync asset id for the uploaded file.'),
+    mediaType: z.enum(['video', 'image', 'audio']).describe('Uploaded media type.'),
+    assetType: z.enum(['VIDEO', 'IMAGE', 'AUDIO']).describe('Sync asset type.'),
+    input: z
+        .object({
+        type: z.enum(['video', 'image', 'audio']),
+        assetId: z.string(),
+    })
+        .describe('Generation input object that can be passed to Sync generation tools.'),
+};

package/dist/tools/overrides.d.ts

@@ -1,5 +1,8 @@
+import type { z } from 'zod';
 type ToolOverride = {
+    title?: string;
     description: string;
+    outputSchema?: Record<string, z.ZodType>;
 };
 export declare function getOverride(toolName: string): ToolOverride | undefined;
 export {};

package/dist/tools/overrides.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overrides.d.ts","sourceRoot":"","sources":["../../src/tools/overrides.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAgCF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE"}
+{"version":3,"file":"overrides.d.ts","sourceRoot":"","sources":["../../src/tools/overrides.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,KAAK,YAAY,GAAG;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;CAC1C,CAAC;AA2JF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE"}

package/dist/tools/overrides.js

@@ -1,27 +1,125 @@
+import { ASSET_THUMBNAIL_INSTRUCTIONS } from '../asset-thumbnail.js';
+import { generationDtoOutputSchema, generationOutputSchema } from './output-schemas.js';
+// Agent-friendly descriptions, keyed by generated tool name
+// (operationIdToToolName). These encode the end-to-end workflow
+// (discover models/voices → upload assets → tts → generate → poll) and tell the
+// agent what to do next, so the tool list reads like a runbook. Endpoints
+// without an entry fall back to the OpenAPI summary.
 const TOOL_OVERRIDES = {
-    'generate_create-generation': {
-        description: 'Create a lipsync video. Provide video + audio inputs (URLs or asset IDs). Returns a generation ID — poll with get-generation until status is COMPLETED.',
+    // --- Speakers to faces (timeline lipsync) ---
+    'transcriptions_get-speaker-analysis': {
+        title: 'Read which face belongs to each speaker',
+        description: 'Read which face in the video belongs to each transcript speaker, by transcription id. Video transcriptions of your own media are analysed automatically; pass wait: true while status is processing. Each speaker is matched (with an avatar, the evidence and a faceTrack: one box per frame of the file where that face is visible) or uncertain (with a reason). To lipsync only the people talking on camera, give each lipsync_create-timeline clip of a matched speaker the url from transcriptions_slice-speaker-face-track as speaker.faceTrackUrl, and keep (lipsync: false, when available) clips of uncertain speakers or where the slice url is null.',
     },
-    'generate_get-generation': {
-        description: 'Get generation status/result by ID. Poll until status is COMPLETED. Result includes output video URL.',
+    'transcriptions_analyze-speakers': {
+        title: 'Match speakers to faces',
+        description: "Start, or retry, the speaker-to-face analysis for a completed video transcription. Pass the transcription's revision and sourceVideoUrl from transcriptions_get. Read transcriptions_get-speaker-analysis first: it usually already exists. Unbilled; up to 2 minutes of video and 8 speakers; 3 calls a minute.",
     },
-    'generations_get-generations': {
-        description: 'List generations for the current organization. Supports pagination.',
+    'transcriptions_slice-speaker-face-track': {
+        title: "Cut a clip's face track",
+        description: "Cut a matched speaker's face track to one clip and get a url for lipsync_create-timeline speaker.faceTrackUrl, so that clip lipsyncs exactly that person. Frames are [startFrame, endFrame) at the video's fps: for a timeline clip pass its startFrame and endFrame + 1. url is null when the face is on none of those frames; keep that clip (lipsync: false) or use detect.",
     },
-    generations_estimate: {
-        description: 'Estimate the cost of a generation before creating it. Returns estimated credits.',
+    // --- Discovery ---
+    models_list: {
+        title: 'List Sync models',
+        description: 'List Sync models with their type, features and deprecation status. Some listed models serve other workflows, such as appearance editing; use only a non-deprecated lipsync model in lipsync_create. Use a returned model name as-is; do not invent model names.',
+    },
+    voices_list: {
+        title: 'List voices',
+        description: 'List available voices: premade ElevenLabs voices plus voices your org has cloned. For "make this image/video say X", use an available returned voice `id` as `voiceId` in lipsync_create with `script` directly. Respect any returned restriction. Use this to find an existing clone before creating another.',
+    },
+    // --- Assets (upload + manage reusable media) ---
+    'assets_create-upload-url': {
+        title: 'Get a media upload URL',
+        description: 'Upload step 1: get a presigned URL for a local file. PUT the raw bytes to the returned `uploadUrl` (same Content-Type), then register it with assets_create using the returned `url`. Use this when your media is not already at a public URL. Max 5GB.',
     },
-    'assets_get-all': {
-        description: 'List all assets (videos, audio files) in the current organization.',
+    assets_create: {
+        title: 'Register a media asset',
+        description: 'Register a direct media URL or import a YouTube, TikTok, Instagram or Facebook video link as a reusable asset. For a social link, pass url, type=VIDEO and the selected projectId. A 409 import_in_progress means the download is running: wait retryAfterMs (15 seconds if absent), then repeat this exact request with the same URL and project. The API reuses the import and returns its saved VIDEO asset when ready. Never use importJobId as an asset ID. Stop on import_failed, import_not_enabled, import_unavailable or import limits and explain the error; do not automatically restart. Returns an asset id for generation inputs or videoAssetId in dubbing_create when available. Import first, then estimate and confirm translation. Link imports have daily limits.',
+    },
+    assets_list: {
+        title: 'List assets',
+        description: 'List assets (video/audio/image) in your organization. Use to find an existing assetId. Pass a small `limit` and narrow with `searchQuery`, `types` or `projectId`. ' +
+            ASSET_THUMBNAIL_INSTRUCTIONS,
     },
     assets_get: {
-        description: 'Get a specific asset by ID. Returns asset details and URL.',
+        title: 'Get an asset',
+        description: 'Get one asset by id (details + URL). ' + ASSET_THUMBNAIL_INSTRUCTIONS,
+    },
+    assets_update: {
+        title: 'Update an asset',
+        description: 'Rename an asset or change its visibility by id. Change only what the user asked for.',
+    },
+    assets_delete: {
+        title: 'Delete an asset',
+        description: 'Delete an asset by id. Use only on an explicit user request, after confirming which asset.',
+    },
+    assets_count: {
+        title: 'Count assets',
+        description: 'Count assets matching the same filters as assets_list (project, creator, search text, type). Returns a number, not the assets.',
+    },
+    'assets_get-download-url': {
+        title: 'Get an asset download URL',
+        description: 'Get a download URL for an accessible asset. Return the URL exactly as given; signed URLs must not be edited.',
+    },
+    // --- Voices (clone + manage) ---
+    voices_clone: {
+        title: 'Clone a voice',
+        description: 'Use this when the user explicitly wants to save a reusable clone of their own voice or a voice they have permission to clone. Confirm the sample and name first; plan limits and provider requirements apply, so do not claim this is free. Pass exactly one of a Sync-hosted `url`, accessible `assetId`, or `sampleUrls` (up to 10 Sync-hosted samples), plus `provider` (elevenlabs) and `name`. Upload/register local samples first. Video samples have audio extracted by the API. Returns a Sync `id`: use that id as `voiceId` in lipsync_create with script, not the provider-specific `voiceId` field. Do not use for Edit Dialogue previews, selecting an existing voice, or designing a voice from a text description. This creates a persistent voice and is not idempotent. On timeout or uncertain failure, list voices and reconcile; never automatically retry. Surface API plan limits, sample errors and duplicate-name errors without retrying or changing accounts.',
+    },
+    voices_delete: {
+        description: 'Delete a cloned voice by id, freeing a clone slot.',
+    },
+    // --- Text-to-speech ---
+    tts_create: {
+        description: 'Synthesize standalone speech audio from text. Use only when the user specifically asks for an audio file or voice preview. Do not use this for "make this image/video say X" lipsync requests — use lipsync_create with `script` and `voiceId` directly.',
+    },
+    // --- Generate + poll ---
+    generations_create: {
+        description: 'Create a lipsync video. Provide a video input (or an image for sync-3) and an audio input, each by `url` or `assetId`. Returns a generation `id` — call generations_get with `wait: true` and omit `timeout` to use the API default. If still pending, poll the same id; when completed, read `outputMediaUrl` (`outputUrl` is a deprecated alias). To choose which face to sync in a multi-person video, pass `options.active_speaker_detection` (auto_detect, or coordinates + frame_number).',
+        outputSchema: generationOutputSchema,
+    },
+    generations_get: {
+        title: 'Get a generation',
+        description: 'Get a generation by id. Pass `wait: true` and omit `timeout` to use the API default. If still pending, poll the same generation id again; never resubmit the generation. When status is COMPLETED, copy the exact `structuredContent.outputMediaUrl` string verbatim; signed URLs must not be reconstructed, shortened, or edited. `outputUrl` is a deprecated alias with the same value.',
+        outputSchema: generationOutputSchema,
+    },
+    generations_list: {
+        title: 'List generations',
+        description: 'List recent generations for your organization to find generation ids or check status. Pass a small `limit`, or narrow with its filters; for the history of one project, prefer projects_list-generations when available.',
+    },
+    'generations_estimate-cost': {
+        title: 'Estimate generation cost',
+        description: 'Estimate Sync cost before generating. For replacement speech, supply model and script (approximate spoken duration), or audioDuration (measured seconds once audio exists). These override duration; do not quote the full source video length for a shorter replacement script. For video cut_off or silence supply videoDuration and the selected syncMode; for images set visualType=image and omit videoDuration. Otherwise supply billable output duration in seconds, optional fps and reasoningEnabled. Explain returned durationEstimate, label script estimates approximate, and disclose that speech synthesis is excluded. If the schema supports workflow=translate-and-dub, use it for both stages and show the returned breakdown; disclose excluded external provider charges. Otherwise this prices lip-sync only. Does not create jobs or reserve credits.',
+    },
+    'generations_get-details': {
+        description: 'Get a generation by id (organization-scoped). Returns status and, when COMPLETED, `outputMediaUrl` (`outputUrl` is a deprecated alias).',
+        outputSchema: generationDtoOutputSchema,
+    },
+    generations_delete: {
+        description: 'Delete a generation by id. Only terminal generations (COMPLETED/FAILED/REJECTED) can be deleted — deleting one that is still processing returns 409.',
+    },
+    generations_estimate: {
+        description: 'Estimate generation cost before creating it. For replacement speech supply script for an approximate spoken-duration quote, or measured audioDuration once audio exists, instead of source video duration. For video cut_off or silence supply videoDuration and the selected syncMode; for images set visualType=image and omit videoDuration. Explain returned durationEstimate; speech synthesis is excluded. For translate-and-dub use source duration and disclose excluded external provider charges.',
+    },
+    // --- Projects (group generations + assets) ---
+    projects_create: {
+        title: 'Create a project',
+        description: 'Create a project to group related generations and assets. Pass the returned `id` as `projectId` to lipsync_create or assets_create so they show up together in Studio. Use by default for a new workflow request, even if an existing project has the same name. Supply a fresh UUID id and preserve it on retries. Project names never select existing work.',
+    },
+    projects_list: {
+        title: 'List projects',
+        description: 'Search and paginate your accessible Sync projects. Each result includes recent generations and assets, so pass a small `limit` and use `searchQuery` only when the user explicitly refers to an existing project. Workflow names are not project references. Never choose the first match when names are ambiguous. Use the returned id as projectId in lipsync_create to work in the same project as the Sync web app.',
+    },
+    projects_get: {
+        title: 'Get a project',
+        description: 'Get one accessible project by id. For its generation history, use projects_list-generations when available.',
     },
-    'models_get-public': {
-        description: 'List all available lipsync models. Use this to discover model IDs for generation.',
+    projects_update: {
+        description: "Update a project's name, description, visibility, or mode.",
     },
-    'generate_get-generations': {
-        description: 'List recent generations. Use to find generation IDs or check batch status.',
+    projects_delete: {
+        description: 'Delete a project. Generations and assets attached to it are not deleted — they just stop being grouped under it.',
     },
 };
 export function getOverride(toolName) {

package/dist/tools/playback-metadata.d.ts

@@ -0,0 +1,4 @@
+import type { HttpClient } from '../http-client.js';
+import type { McpToolDefinition } from './generator.js';
+export declare function createPlaybackMetadataTool(http: HttpClient): McpToolDefinition;
+//# sourceMappingURL=playback-metadata.d.ts.map

package/dist/tools/playback-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playback-metadata.d.ts","sourceRoot":"","sources":["../../src/tools/playback-metadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAkBxD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAoC9E"}

package/dist/tools/playback-metadata.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+// Narrow read projection of the API's AssetMetadataSchema. Analysis, transcript,
+// provider and face-detection fields never cross the app boundary.
+const playbackMetadata = z.object({
+    assetId: z.uuid(),
+    duration: z.number().finite().nonnegative().nullish(),
+    fps: z.number().finite().positive().nullish(),
+    frameCount: z.number().int().nonnegative().nullish(),
+    width: z.number().int().positive().nullish(),
+    height: z.number().int().positive().nullish(),
+    codec: z.string().nullish(),
+    format: z.string().nullish(),
+    proxyPath: z.url().nullish(),
+    proxyRequested: z.boolean().optional(),
+    thumbnailsManifestUrl: z.url().nullish(),
+});
+export function createPlaybackMetadataTool(http) {
+    const input = z.object({ assetId: z.uuid() }).strict();
+    return {
+        name: 'assets_get-playback-metadata',
+        title: 'Read video playback metadata',
+        description: 'Read timing, frame rate, dimensions and playback proxy metadata for an accessible Sync asset. Requires a connected user; API keys return unsupported. Missing metadata stays unknown. Does not analyze media, read transcripts, or modify assets.',
+        inputSchema: input.shape,
+        outputSchema: { supported: z.boolean(), metadata: playbackMetadata.nullable() },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: async (args, context) => {
+            const { assetId } = input.parse(args);
+            const identity = z
+                .object({ account: z.object({ id: z.uuid() }).nullable() })
+                .parse(await http.request('get', '/v2/oauth/account', { signal: context?.signal }));
+            if (!identity.account)
+                return { supported: false, metadata: null };
+            const rows = playbackMetadata
+                .array()
+                .max(1)
+                .parse(await http.request('get', '/v2/asset-metadata/by-asset', {
+                query: { assetId },
+                signal: context?.signal,
+            }));
+            const metadata = rows[0] ?? null;
+            if (metadata && metadata.assetId !== assetId)
+                throw new Error('Playback metadata does not match the requested asset.');
+            return { supported: true, metadata };
+        },
+    };
+}

package/dist/tools/project-destination.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { HttpClient } from '../http-client.js';
+export declare const newProjectFields: {
+    projectCreationKey: z.ZodOptional<z.ZodUUID>;
+};
+export declare function assertProjectDestination(projectId?: string, projectName?: string, projectCreationKey?: string): void;
+export declare function createProjectId(http: HttpClient, { name, projectCreationKey, idempotencyKey, defaultWorkflow, }: {
+    name: string;
+    projectCreationKey?: string;
+    idempotencyKey?: string;
+    defaultWorkflow: 'lipsync' | 'image_to_video' | 'translate_and_dub';
+}, signal?: AbortSignal): Promise<string>;
+//# sourceMappingURL=project-destination.d.ts.map

package/dist/tools/project-destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-destination.d.ts","sourceRoot":"","sources":["../../src/tools/project-destination.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,eAAO,MAAM,gBAAgB;IAC3B,kBAAkB;CAMnB,CAAC;AAEF,wBAAgB,wBAAwB,CACtC,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,EACpB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,IAAI,CAQN;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,UAAU,EAChB,EACE,IAAI,EACJ,kBAAkB,EAClB,cAAc,EACd,eAAe,GAChB,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,SAAS,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;CACrE,EACD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CA4BjB"}

package/dist/tools/project-destination.js

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const newProjectFields = {
+    projectCreationKey: z
+        .uuid()
+        .optional()
+        .describe('Fresh random UUID identifying this NEW project creation, not a project ID. Required for keyed generation without projectId. Persist this key, name and generation key on retries; the server derives a separate project UUID.'),
+};
+export function assertProjectDestination(projectId, projectName, projectCreationKey) {
+    if (projectId !== undefined && !projectId.trim())
+        throw new Error('projectId must not be empty.');
+    if (projectId !== undefined && projectName !== undefined)
+        throw new Error('Provide either projectId or projectName, not both.');
+    if (projectId !== undefined && projectCreationKey !== undefined)
+        throw new Error('Provide either projectId or projectCreationKey, not both.');
+    if (projectName !== undefined && !projectName.trim())
+        throw new Error('projectName must not be empty.');
+}
+export async function createProjectId(http, { name, projectCreationKey, idempotencyKey, defaultWorkflow, }, signal) {
+    // Clients holding a tool list from before projectCreationKey existed still send keyed
+    // requests. They get an unkeyed new project; only a lost-response retry can then conflict.
+    let id;
+    if (projectCreationKey !== undefined) {
+        z.uuid().parse(projectCreationKey);
+        // A creation key cannot be substituted with an existing project's UUID.
+        const bytes = createHash('sha256')
+            .update('sync:mcp:new-project:v1\0')
+            .update(projectCreationKey.toLowerCase())
+            .update('\0')
+            .update(idempotencyKey ?? '')
+            .digest();
+        bytes[6] = (bytes[6] & 0x0f) | 0x80;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = bytes.subarray(0, 16).toString('hex');
+        id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    signal?.throwIfAborted();
+    const project = z.object({ id: z.string().min(1) }).parse(await http.request('post', '/v2/projects', {
+        signal,
+        body: { name, defaultWorkflow, ...(id ? { id } : {}) },
+    }));
+    if (id && project.id !== id)
+        throw new Error('Sync returned a different project than the one requested.');
+    return project.id;
+}