@sync.so/mcp-server 0.1.4 → 0.2.0

package/dist/toolsets.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Toolsets for the local (stdio) server. It used to list a tool for every public API
+ * operation (65+), which crowds an agent's context; by default it now lists the curated
+ * set the hosted server offers, plus what those workflows need. An operator picks more
+ * with SYNC_MCP_TOOLSETS or --toolsets; agents cannot. The hosted server ignores this.
+ */
+export declare const TOOLSETS: readonly ['default', 'lipsync', 'dubbing', 'assets', 'projects', 'transcription', 'voices', 'admin', 'all'];
+export type Toolset = (typeof TOOLSETS)[number];
+type Category = Exclude<Toolset, 'default' | 'all'>;
+/** The toolset a tool belongs to, or undefined for a tool only `all` lists. */
+export declare function toolCategory(name: string): Category | undefined;
+export declare function toolsetIncludes(selection: readonly Toolset[] | undefined, name: string, hostedTools: ReadonlySet<string>): boolean;
+/** Comma- or space-separated toolset names; empty means the default. */
+export declare function parseToolsets(value: string | undefined): Toolset[] | undefined;
+/** The server instructions' note on what this connection lists, or '' when it lists everything. */
+export declare function toolsetInstruction(selection: readonly Toolset[] | undefined): string;
+export {};
+//# sourceMappingURL=toolsets.d.ts.map

package/dist/toolsets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolsets.d.ts","sourceRoot":"","sources":["../src/toolsets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,YACnB,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,UAAU,EACV,eAAe,EACf,QAAQ,EACR,OAAO,EACP,KAAK,CACG,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAChD,KAAK,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,SAAS,GAAG,KAAK,CAAC,CAAC;AAiGpD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAK/D;AAYD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,EACzC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,OAAO,CAOT;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAY9E;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAAG,MAAM,CAIpF"}

package/dist/toolsets.js

@@ -0,0 +1,157 @@
+/**
+ * Toolsets for the local (stdio) server. It used to list a tool for every public API
+ * operation (65+), which crowds an agent's context; by default it now lists the curated
+ * set the hosted server offers, plus what those workflows need. An operator picks more
+ * with SYNC_MCP_TOOLSETS or --toolsets; agents cannot. The hosted server ignores this.
+ */
+export const TOOLSETS = [
+    'default',
+    'lipsync',
+    'dubbing',
+    'assets',
+    'projects',
+    'transcription',
+    'voices',
+    'admin',
+    'all',
+];
+// Listed with every selection: reading jobs, account state and the app's own helpers.
+const CORE = new Set([
+    'jobs_get',
+    'jobs_wait',
+    'account_get-context',
+    'organizations_list',
+    'organizations_select',
+    'account_get-usage',
+    'models_list',
+    'feedback_send',
+    'generations_get',
+    'generations_list',
+    'generations_estimate-cost',
+    'generations_get-costs',
+    'generations_get-continuation',
+    'assets_get-playback-metadata',
+    'assets_list-creators',
+    // App-only tools; isToolVisible still hides them from clients without the app UI.
+    'analytics_track-event',
+    'app_open',
+    'studio-views_get',
+    'studio-views_open-project',
+    'studio-views_refresh-project',
+    'studio-views_refresh-assets',
+    'studio-views_show-generation',
+    'studio-views_continue-generation',
+    'studio-views_register',
+    'studio-views_ack',
+    'studio-drafts_get',
+    'studio-drafts_update',
+    'studio-drafts_save',
+    'studio-drafts_ack',
+]);
+// Hand-written tools. Generated tools fall back to their API controller below.
+const CATEGORY_BY_TOOL = {
+    lipsync_create: 'lipsync',
+    'lipsync_create-from-assets': 'lipsync',
+    'lipsync_create-timeline': 'lipsync',
+    'audio-trims_create': 'lipsync',
+    'audio-trims_get': 'lipsync',
+    'dialogue_get-options': 'lipsync',
+    'dialogue_upload-source': 'lipsync',
+    'dialogue-transcriptions_create': 'lipsync',
+    'dialogue-transcriptions_get': 'lipsync',
+    'dialogue-previews_create': 'lipsync',
+    'dialogue-previews_get': 'lipsync',
+    'dialogue-videos_estimate': 'lipsync',
+    'dialogue-videos_create': 'lipsync',
+    dubbing_create: 'dubbing',
+    'dubbing_get-options': 'dubbing',
+    'translation-previews_estimate': 'dubbing',
+    'translation-previews_create': 'dubbing',
+    'translation-previews_get': 'dubbing',
+    // Feature-gated: listed only to accounts with the feature (account-features.ts).
+    scenes_detect: 'lipsync',
+    stems_separate: 'assets',
+    assets_upload: 'assets',
+    'assets_open-upload-widget': 'assets',
+    projects_rename: 'projects',
+    'speech-previews_get-options': 'voices',
+    'speech-previews_create': 'voices',
+    'speech-previews_get': 'voices',
+    // Creates a persistent voice from someone's recording; not idempotent.
+    voices_clone: 'admin',
+    // Batches of /v2/generate bodies; dubbing lists them too, for localizing many videos.
+    batches_create: 'lipsync',
+    batches_get: 'lipsync',
+    batches_list: 'lipsync',
+};
+// Tools a second toolset lists as well.
+const ALSO_IN = {
+    batches_create: 'dubbing',
+    batches_get: 'dubbing',
+    batches_list: 'dubbing',
+};
+const CATEGORY_BY_CONTROLLER = {
+    generate: 'lipsync',
+    generations: 'lipsync',
+    'dialogue-edits': 'lipsync',
+    integrations: 'dubbing',
+    dubbing: 'dubbing',
+    assets: 'assets',
+    projects: 'projects',
+    transcriptions: 'transcription',
+    voices: 'voices',
+    tts: 'voices',
+    'tts-jobs': 'voices',
+};
+// Deletes stay in admin whatever their controller.
+const DELETES = /(?:^|[_-])(?:delete|remove)(?:[_-]|$)/;
+/** The toolset a tool belongs to, or undefined for a tool only `all` lists. */
+export function toolCategory(name) {
+    if (DELETES.test(name))
+        return 'admin';
+    if (CATEGORY_BY_TOOL[name])
+        return CATEGORY_BY_TOOL[name];
+    const controller = name.includes('_') ? name.slice(0, name.indexOf('_')) : undefined;
+    return controller ? CATEGORY_BY_CONTROLLER[controller] : undefined;
+}
+/**
+ * The default: what the hosted server lists, without admin tools, plus what the curated
+ * workflows need there: jobs_get and jobs_wait, and the transcription tools whose speaker
+ * face tracks become lipsync_create-timeline clips.
+ */
+function inDefaultToolset(name, hostedTools) {
+    if (toolCategory(name) === 'admin')
+        return false;
+    return CORE.has(name) || hostedTools.has(name) || toolCategory(name) === 'transcription';
+}
+export function toolsetIncludes(selection, name, hostedTools) {
+    const chosen = selection?.length ? selection : ['default'];
+    if (chosen.includes('all'))
+        return true;
+    if (chosen.includes('default') && inDefaultToolset(name, hostedTools))
+        return true;
+    if (CORE.has(name))
+        return true;
+    const categories = [toolCategory(name), ALSO_IN[name]];
+    return categories.some((category) => category !== undefined && chosen.includes(category));
+}
+/** Comma- or space-separated toolset names; empty means the default. */
+export function parseToolsets(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const names = value
+        .split(/[\s,]+/)
+        .map((name) => name.trim().toLowerCase())
+        .filter(Boolean);
+    const unknown = names.filter((name) => !TOOLSETS.includes(name));
+    if (unknown.length > 0)
+        throw new Error(`Unknown toolset ${unknown.map((name) => `"${name}"`).join(', ')}; use ${TOOLSETS.join(', ')}.`);
+    return [...new Set(names)];
+}
+/** The server instructions' note on what this connection lists, or '' when it lists everything. */
+export function toolsetInstruction(selection) {
+    const chosen = selection?.length ? selection : ['default'];
+    if (chosen.includes('all'))
+        return '';
+    return `This local server lists the ${chosen.join(', ')} Sync toolset${chosen.length > 1 ? 's' : ''}, not every API tool; delete tools and voice cloning are in admin. If the user needs a tool that is not listed, tell them to restart the server with SYNC_MCP_TOOLSETS=all (or --toolsets all), or to add toolsets such as default,admin.`;
+}

package/dist/update-check.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Local (stdio) installs go stale silently: npx keeps running whatever it cached. At
+ * startup the CLI asks the npm registry for the latest version, at most once a day, and
+ * the server tells the agent when this copy is older. The hosted server deploys on every
+ * merge, so it never checks. Any failure means no notice.
+ */
+export declare const UPDATE_CHECK_TIMEOUT_MS = 2000;
+export declare const UPDATE_CHECK_TTL_MS: number;
+export type AvailableUpdate = {
+    current: string;
+    latest: string;
+};
+export type UpdateCheck = {
+    /** The newer version once the check has found one; never waits for it. */
+    available: () => AvailableUpdate | undefined;
+    /** Settles when the check finishes. Never rejects. */
+    done: Promise<void>;
+};
+/** SYNC_MCP_UPDATE_CHECK accepts off/false/0/no and on/true/1/yes (default). */
+export declare function parseUpdateCheck(value: string | undefined): boolean | undefined;
+/** Semver precedence: negative when a < b, positive when a > b, undefined when unparsable. */
+export declare function compareVersions(a: string, b: string): number | undefined;
+export declare function updateInstruction({ current, latest }: AvailableUpdate): string;
+export declare function updateToolNotice({ current, latest }: AvailableUpdate): string;
+/** The CLI's gate: local (stdio) installs only, unless opted out or running in CI. */
+export declare function startConfiguredUpdateCheck(config: {
+    transport: 'stdio' | 'http';
+    updateCheck?: boolean;
+}, currentVersion: string, env?: NodeJS.ProcessEnv, options?: Omit<Parameters<typeof startUpdateCheck>[0], 'currentVersion'>): UpdateCheck | undefined;
+/** Starts the check in the background and returns at once. */
+export declare function startUpdateCheck(options: {
+    currentVersion: string;
+    cacheFile?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+}): UpdateCheck;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../src/update-check.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C,eAAO,MAAM,mBAAmB,QAAsB,CAAC;AAOvD,MAAM,MAAM,eAAe,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG;IACxB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,eAAe,GAAG,SAAS,CAAC;IAC7C,sDAAsD;IACtD,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB,CAAC;AAIF,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAM/E;AAWD,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASxE;AAqBD,wBAAgB,iBAAiB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,eAAe,GAAG,MAAM,CAE9E;AAED,wBAAgB,gBAAgB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,eAAe,GAAG,MAAM,CAE7E;AAED,sFAAsF;AACtF,wBAAgB,0BAA0B,CACxC,MAAM,EAAE;IAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,EAC9D,cAAc,EAAE,MAAM,EACtB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,OAAO,GAAE,IAAI,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAM,GAC3E,WAAW,GAAG,SAAS,CAGzB;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,WAAW,CASd"}

package/dist/update-check.js

@@ -0,0 +1,150 @@
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Local (stdio) installs go stale silently: npx keeps running whatever it cached. At
+ * startup the CLI asks the npm registry for the latest version, at most once a day, and
+ * the server tells the agent when this copy is older. The hosted server deploys on every
+ * merge, so it never checks. Any failure means no notice.
+ */
+export const UPDATE_CHECK_TIMEOUT_MS = 2_000;
+export const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+const LATEST_URL = 'https://registry.npmjs.org/@sync.so/mcp-server/latest';
+const CACHE_FILE = path.join(os.homedir(), '.config', 'sync', 'mcp-update-check.json');
+const HOSTED_MCP_URL = 'https://mcp.sync.so/mcp';
+const UPDATE_COMMAND = 'npx -y @sync.so/mcp-server@latest';
+/** SYNC_MCP_UPDATE_CHECK accepts off/false/0/no and on/true/1/yes (default). */
+export function parseUpdateCheck(value) {
+    if (value === undefined || value.trim() === '')
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (['off', 'false', '0', 'no'].includes(normalized))
+        return false;
+    if (['on', 'true', '1', 'yes'].includes(normalized))
+        return true;
+    throw new Error(`SYNC_MCP_UPDATE_CHECK must be on or off, not "${value}"`);
+}
+/** CI runs are unattended and often offline; CI=false or CI=0 still checks. */
+function isCi(env = process.env) {
+    const value = env.CI?.trim().toLowerCase();
+    return Boolean(value) && value !== 'false' && value !== '0';
+}
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/;
+/** Semver precedence: negative when a < b, positive when a > b, undefined when unparsable. */
+export function compareVersions(a, b) {
+    const left = SEMVER.exec(a.trim());
+    const right = SEMVER.exec(b.trim());
+    if (!left || !right)
+        return undefined;
+    for (let index = 1; index <= 3; index++) {
+        const difference = Number(left[index]) - Number(right[index]);
+        if (difference !== 0)
+            return Math.sign(difference);
+    }
+    return comparePrerelease(left[4], right[4]);
+}
+function comparePrerelease(a, b) {
+    // A release outranks any of its prereleases.
+    if (a === undefined || b === undefined)
+        return a === b ? 0 : a === undefined ? 1 : -1;
+    const left = a.split('.');
+    const right = b.split('.');
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const x = left[index];
+        const y = right[index];
+        if (x === undefined || y === undefined)
+            return x === undefined ? -1 : 1;
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric)
+            return Math.sign(Number(x) - Number(y));
+        if (xNumeric !== yNumeric)
+            return xNumeric ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+export function updateInstruction({ current, latest }) {
+    return `This sync. MCP server is version ${current}; version ${latest} is available. Tell the user to update: restart with \`${UPDATE_COMMAND}\` (or reinstall), or switch to the hosted server at ${HOSTED_MCP_URL}, which is always current.`;
+}
+export function updateToolNotice({ current, latest }) {
+    return `Update available: this sync. MCP server is ${current} and ${latest} is out. Tell the user to restart it with \`${UPDATE_COMMAND}\`, or to use the hosted server at ${HOSTED_MCP_URL}.`;
+}
+/** The CLI's gate: local (stdio) installs only, unless opted out or running in CI. */
+export function startConfiguredUpdateCheck(config, currentVersion, env = process.env, options = {}) {
+    if (config.transport !== 'stdio' || config.updateCheck === false || isCi(env))
+        return undefined;
+    return startUpdateCheck({ ...options, currentVersion });
+}
+/** Starts the check in the background and returns at once. */
+export function startUpdateCheck(options) {
+    let available;
+    const current = options.currentVersion;
+    const done = findLatest(options)
+        .then((latest) => {
+        if (latest && (compareVersions(latest, current) ?? 0) > 0)
+            available = { current, latest };
+    })
+        .catch(() => undefined);
+    return { done, available: () => available };
+}
+async function findLatest(options) {
+    const cacheFile = options.cacheFile ?? CACHE_FILE;
+    const now = options.now?.() ?? Date.now();
+    const cached = await readCache(cacheFile);
+    const age = cached ? now - Date.parse(cached.checkedAt) : Number.NaN;
+    if (cached && age >= 0 && age < UPDATE_CHECK_TTL_MS)
+        return cached.latest;
+    const latest = await fetchLatest(options.fetch ?? fetch, options.timeoutMs);
+    // Failures are cached too, so an offline machine still asks at most once a day.
+    await writeCache(cacheFile, {
+        checkedAt: new Date(now).toISOString(),
+        ...(latest ? { latest } : {}),
+    });
+    return latest;
+}
+async function fetchLatest(fetchImpl, timeoutMs = UPDATE_CHECK_TIMEOUT_MS) {
+    try {
+        const signal = AbortSignal.timeout(timeoutMs);
+        const response = await fetchImpl(LATEST_URL, {
+            headers: { accept: 'application/json' },
+            signal,
+        });
+        if (!response.ok)
+            return undefined;
+        const body = await response.json();
+        const version = body && typeof body === 'object' && 'version' in body ? body.version : undefined;
+        return typeof version === 'string' && SEMVER.test(version) ? version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readCache(file) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return undefined;
+        const { checkedAt, latest } = parsed;
+        if (typeof checkedAt !== 'string' || Number.isNaN(Date.parse(checkedAt)))
+            return undefined;
+        return {
+            checkedAt,
+            ...(typeof latest === 'string' && SEMVER.test(latest) ? { latest } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeCache(file, entry) {
+    try {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, `${JSON.stringify(entry)}\n`, 'utf8');
+    }
+    catch {
+        // A read-only home only means checking again next start.
+    }
+}

package/dist/upload-runtime.d.ts

@@ -0,0 +1,45 @@
+export type UploadRuntimeConfig = {
+    maxBytes: number;
+    maxConcurrent: number;
+    maxQueued: number;
+    retryAfterMs: number;
+    timeoutMs: number;
+};
+export type UploadRuntimeStats = {
+    active: number;
+    queued: number;
+    rejected: number;
+    completed: number;
+    failed: number;
+    cleanupFailures: number;
+    downloadedBytes: number;
+    uploadedBytes: number;
+};
+export declare function getUploadRuntimeConfig(env?: Record<string, string | undefined>): UploadRuntimeConfig;
+export declare class UploadOverloadedError extends Error {
+    readonly code = "UPLOAD_CAPACITY_EXCEEDED";
+    readonly retryable = true;
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+export declare class UploadTimeoutError extends Error {
+    readonly code = "UPLOAD_TIMEOUT";
+    readonly retryable = true;
+    readonly retryAfterMs: number;
+    constructor(timeoutMs: number, retryAfterMs: number);
+}
+export declare class UploadRuntime {
+    #private;
+    readonly config: UploadRuntimeConfig;
+    constructor(config?: UploadRuntimeConfig);
+    run<T>(operation: (signal: AbortSignal) => Promise<T>, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    recordDownloadedBytes(bytes: number): void;
+    recordUploadedBytes(bytes: number): void;
+    recordCleanupFailure(): void;
+    snapshot(): UploadRuntimeStats;
+}
+export declare const uploadRuntime: UploadRuntime;
+//# sourceMappingURL=upload-runtime.d.ts.map

package/dist/upload-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-runtime.d.ts","sourceRoot":"","sources":["../src/upload-runtime.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAgBF,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,mBAAmB,CAQrB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,8BAA8B;IAC3C,QAAQ,CAAC,SAAS,QAAQ;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,YAAY,YAAY,EAAE,MAAM,EAI/B;CACF;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,SAAS,QAAQ;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,YAAY,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAIlD;CACF;AAQD,qBAAa,aAAa;;IACxB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAarC,YAAY,MAAM,GAAE,mBAA8C,EAEjE;IAEK,GAAG,CAAC,CAAC,EACT,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACzD,OAAO,CAAC,CAAC,CAAC,CAmCZ;IAED,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEzC;IAED,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEvC;IAED,oBAAoB,IAAI,IAAI,CAE3B;IAED,QAAQ,IAAI,kBAAkB,CAE7B;CAgDF;AAED,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/upload-runtime.js

@@ -0,0 +1,156 @@
+import { combineSignals } from './abort-signals.js';
+const MIB = 1024 * 1024;
+function positiveInteger(value, fallback) {
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function nonNegativeInteger(value, fallback) {
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+export function getUploadRuntimeConfig(env = process.env) {
+    return {
+        maxBytes: positiveInteger(env.MCP_UPLOAD_MAX_BYTES, 512 * MIB),
+        maxConcurrent: positiveInteger(env.MCP_UPLOAD_CONCURRENCY, 2),
+        maxQueued: nonNegativeInteger(env.MCP_UPLOAD_MAX_QUEUED, 8),
+        retryAfterMs: positiveInteger(env.MCP_UPLOAD_RETRY_AFTER_MS, 5_000),
+        timeoutMs: positiveInteger(env.MCP_UPLOAD_TIMEOUT_MS, 15 * 60_000),
+    };
+}
+export class UploadOverloadedError extends Error {
+    code = 'UPLOAD_CAPACITY_EXCEEDED';
+    retryable = true;
+    retryAfterMs;
+    constructor(retryAfterMs) {
+        super('Upload capacity is temporarily full. Retry the request later.');
+        this.name = 'UploadOverloadedError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class UploadTimeoutError extends Error {
+    code = 'UPLOAD_TIMEOUT';
+    retryable = true;
+    retryAfterMs;
+    constructor(timeoutMs, retryAfterMs) {
+        super(`Upload timed out after ${timeoutMs}ms. Retry the request later.`);
+        this.name = 'UploadTimeoutError';
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class UploadRuntime {
+    config;
+    #stats = {
+        active: 0,
+        queued: 0,
+        rejected: 0,
+        completed: 0,
+        failed: 0,
+        cleanupFailures: 0,
+        downloadedBytes: 0,
+        uploadedBytes: 0,
+    };
+    #waiters = [];
+    constructor(config = getUploadRuntimeConfig()) {
+        this.config = config;
+    }
+    async run(operation, options = {}) {
+        const timeoutMs = options.timeoutMs ?? this.config.timeoutMs;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort(new UploadTimeoutError(timeoutMs, this.config.retryAfterMs));
+        }, timeoutMs);
+        timeout.unref();
+        const { signal, dispose } = combineSignals(options.signal ? [options.signal, controller.signal] : [controller.signal]);
+        let release;
+        try {
+            release = await this.#acquire(signal);
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            dispose();
+            throw error;
+        }
+        let started = false;
+        try {
+            signal.throwIfAborted();
+            started = true;
+            const result = await operation(signal);
+            this.#stats.completed += 1;
+            return result;
+        }
+        catch (error) {
+            // Admission cancellation is not a failed transfer: no operation ran.
+            if (started)
+                this.#stats.failed += 1;
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+            dispose();
+            release();
+        }
+    }
+    recordDownloadedBytes(bytes) {
+        this.#stats.downloadedBytes += bytes;
+    }
+    recordUploadedBytes(bytes) {
+        this.#stats.uploadedBytes += bytes;
+    }
+    recordCleanupFailure() {
+        this.#stats.cleanupFailures += 1;
+    }
+    snapshot() {
+        return { ...this.#stats };
+    }
+    async #acquire(signal) {
+        if (signal.aborted)
+            throw signal.reason;
+        if (this.#stats.active < this.config.maxConcurrent) {
+            this.#stats.active += 1;
+            return this.#releaseOnce();
+        }
+        if (this.#stats.queued >= this.config.maxQueued) {
+            this.#stats.rejected += 1;
+            throw new UploadOverloadedError(this.config.retryAfterMs);
+        }
+        this.#stats.queued += 1;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                const index = this.#waiters.indexOf(waiter);
+                if (index !== -1) {
+                    this.#waiters.splice(index, 1);
+                    this.#stats.queued -= 1;
+                }
+                reject(signal.reason);
+            };
+            const waiter = {
+                resolve,
+                reject,
+                cleanup: () => signal.removeEventListener('abort', onAbort),
+            };
+            this.#waiters.push(waiter);
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    #releaseOnce() {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const waiter = this.#waiters.shift();
+            if (waiter) {
+                this.#stats.queued -= 1;
+                waiter.cleanup();
+                waiter.resolve(this.#releaseOnce());
+                return;
+            }
+            this.#stats.active = Math.max(0, this.#stats.active - 1);
+        };
+    }
+}
+export const uploadRuntime = new UploadRuntime();

package/dist/upload-source.d.ts

@@ -0,0 +1,4 @@
+import { Agent } from 'undici';
+export declare function validatedUploadSourceUrl(value: string): string;
+export declare function createUploadSourceDispatcher(signal: AbortSignal): Agent;
+//# sourceMappingURL=upload-source.d.ts.map

package/dist/upload-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-source.d.ts","sourceRoot":"","sources":["../src/upload-source.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAU/B,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY9D;AAgBD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAKvE"}

package/dist/upload-source.js

@@ -0,0 +1,46 @@
+import { lookup } from 'node:dns';
+import { isIP } from 'node:net';
+import ipaddr from 'ipaddr.js';
+import { Agent } from 'undici';
+function isPublicAddress(value) {
+    if (!isIP(value))
+        return false;
+    const address = ipaddr.parse(value);
+    if (address.range() !== 'unicast')
+        return false;
+    // IPv6 unallocated space is not public, even if it has no named special range.
+    return address.kind() === 'ipv4' || address.match(ipaddr.parse('2000::'), 3);
+}
+export function validatedUploadSourceUrl(value) {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.port) {
+        throw new Error('Upload sources require HTTP(S), no credentials, and the protocol default port.');
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, '');
+    if (isIP(hostname) && !isPublicAddress(hostname)) {
+        throw new Error('Upload sources must have a public destination.');
+    }
+    return url.href;
+}
+const publicLookup = (hostname, options, callback) => {
+    // Resolve inside the socket connection, and return only these checked addresses
+    // to the connector. There is no subsequent DNS resolution for a rebind to alter.
+    lookup(hostname, { all: true, verbatim: true }, (error, addresses) => {
+        if (error)
+            return callback(error, '');
+        const first = addresses[0];
+        if (!first || addresses.some(({ address }) => !isPublicAddress(address))) {
+            return callback(new Error('Upload sources must resolve only to public destinations.'), '');
+        }
+        if (options.all)
+            callback(null, addresses);
+        else
+            callback(null, first.address, first.family);
+    });
+};
+export function createUploadSourceDispatcher(signal) {
+    // An explicit direct agent bypasses global/proxy dispatchers. A transfer owns
+    // its connections so arbitrary source hosts cannot accumulate cached pools.
+    const connect = { lookup: publicLookup, signal };
+    return new Agent({ connect });
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAGA,eAAO,MAAiB,eAAe,QAEtC,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+import { createRequire } from 'node:module';
+// Report the published package version, not a hand-maintained copy.
+export const { version: PACKAGE_VERSION } = createRequire(import.meta.url)('../package.json');