@sync.so/mcp-server 0.1.3 → 0.2.0

package/dist/cli.js

@@ -1,29 +1,25 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { resolveConfig } from './config.js';
-import { createSyncMcpServer } from './server.js';
+import { createMcpServerFactory, createSyncMcpServer } from './server.js';
+import { parseToolsets } from './toolsets.js';
+import { startConfiguredUpdateCheck } from './update-check.js';
+import { PACKAGE_VERSION } from './version.js';
 async function main() {
     const args = process.argv.slice(2);
     const config = resolveConfig(parseArgs(args));
-    const server = await createSyncMcpServer(config);
     if (config.transport === 'stdio') {
+        // Started before auth and the spec fetch, and never awaited.
+        const updateCheck = startConfiguredUpdateCheck(config, PACKAGE_VERSION);
+        const server = await createSyncMcpServer(config, { updateCheck });
         const transport = new StdioServerTransport();
         await server.connect(transport);
     }
     else {
-        // HTTP transport - import dynamically to avoid bundling when unused
-        const { StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
-        const http = await import('node:http');
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined,
-        });
-        await server.connect(transport);
-        const httpServer = http.createServer(async (req, res) => {
-            await transport.handleRequest(req, res);
-        });
-        httpServer.listen(config.port, () => {
-            process.stderr.write(`Sync MCP server listening on http://localhost:${config.port}\n`);
-        });
+        // HTTP transport: each session gets its own McpServer instance
+        const factory = await createMcpServerFactory(config);
+        const { startHttpServer } = await import('./http-server.js');
+        await startHttpServer(factory, config);
     }
 }
 function parseArgs(args) {
@@ -47,6 +43,16 @@ function parseArgs(args) {
             result.port = Number.parseInt(next, 10);
             i++;
         }
+        else if (arg === '--no-spend-confirmation') {
+            result.spendConfirmation = false;
+        }
+        else if (arg === '--no-update-check') {
+            result.updateCheck = false;
+        }
+        else if (arg === '--toolsets' && next) {
+            result.toolsets = parseToolsets(next);
+            i++;
+        }
         else if (arg === '--help' || arg === '-h') {
             printUsage();
             process.exit(0);
@@ -62,6 +68,14 @@ Options:
   --base-url <url>    API base URL (default: https://api.sync.so)
   --transport <type>  stdio (default) or http
   --port <port>       HTTP port (default: 3002, only with --transport http)
+  --no-spend-confirmation
+                      Unattended automation: drop the cost-quote and confirm-before-paying
+                      instructions (or set SYNC_MCP_SPEND_CONFIRMATION=off)
+  --no-update-check   Skip the daily npm check for a newer version (or set
+                      SYNC_MCP_UPDATE_CHECK=off; skipped when CI is set)
+  --toolsets <list>   stdio only: comma-separated tools to list (or set SYNC_MCP_TOOLSETS):
+                      default, lipsync, dubbing, assets, projects, transcription,
+                      voices, admin or all (default: the hosted set without admin)
   -h, --help          Show this help message
 `);
 }

package/dist/client-profile.d.ts

@@ -0,0 +1,10 @@
+export type ClientProfile = Readonly<{
+    name: 'chatgpt' | 'codex' | 'claude' | 'generic';
+    supportsAppUi: boolean;
+    supportsUploads: boolean;
+    defaultProjectName: string;
+}>;
+/** Presentation only. These untrusted handshake names never grant permissions. */
+export declare function resolveClientProfile(name?: string): ClientProfile;
+export declare const UNSUPPORTED_UPLOAD_MESSAGE = "This client does not support the ChatGPT file bridge or upload widget. For a local file, call assets_create-upload-url, PUT the file bytes to the returned uploadUrl with the same Content-Type, register the returned url with assets_create, and pass the asset id as imageAssetId, videoAssetId or audioAssetId. Public or Sync-hosted URLs and existing Sync asset IDs also work in lipsync_create.";
+//# sourceMappingURL=client-profile.d.ts.map

package/dist/client-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-profile.d.ts","sourceRoot":"","sources":["../src/client-profile.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IACjD,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AA6BH,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAgBjE;AAED,eAAO,MAAM,0BAA0B,4YACoW,CAAC"}

package/dist/client-profile.js

@@ -0,0 +1,45 @@
+const GENERIC = Object.freeze({
+    name: 'generic',
+    supportsAppUi: false,
+    supportsUploads: false,
+    defaultProjectName: 'Sync generations',
+});
+const CHATGPT = Object.freeze({
+    name: 'chatgpt',
+    supportsAppUi: true,
+    supportsUploads: true,
+    defaultProjectName: 'ChatGPT generations',
+});
+const CODEX = Object.freeze({
+    name: 'codex',
+    supportsAppUi: true,
+    // The hosted OpenAI connector supplies validated fileParams for this client too.
+    // Keep its project default separate without rejecting those files by host name.
+    supportsUploads: true,
+    defaultProjectName: 'Sync generations',
+});
+const CLAUDE = Object.freeze({
+    name: 'claude',
+    supportsAppUi: false,
+    supportsUploads: false,
+    defaultProjectName: 'Claude generations',
+});
+/** Presentation only. These untrusted handshake names never grant permissions. */
+export function resolveClientProfile(name) {
+    switch ((name ?? '').toLowerCase()) {
+        case 'chatgpt':
+        case 'openai':
+        case 'openai-chatgpt':
+        case 'openai-mcp':
+            return CHATGPT;
+        case 'openai-mcp (codex)':
+            return CODEX;
+        case 'claude':
+        case 'claude-ai':
+            return CLAUDE;
+        // Muse remains generic until Meta documentation or a real handshake verifies its alias.
+        default:
+            return GENERIC;
+    }
+}
+export const UNSUPPORTED_UPLOAD_MESSAGE = 'This client does not support the ChatGPT file bridge or upload widget. For a local file, call assets_create-upload-url, PUT the file bytes to the returned uploadUrl with the same Content-Type, register the returned url with assets_create, and pass the asset id as imageAssetId, videoAssetId or audioAssetId. Public or Sync-hosted URLs and existing Sync asset IDs also work in lipsync_create.';

package/dist/config.d.ts

@@ -1,8 +1,25 @@
+import { type Toolset } from './toolsets.js';
 export type SyncMcpConfig = {
     apiKey?: string;
     baseUrl: string;
+    oauthAuthorizationUrl?: string;
     transport: 'stdio' | 'http';
     port: number;
+    /** False when the operator pre-approved spending; see spend-confirmation.ts. */
+    spendConfirmation?: boolean;
+    /** stdio only: false skips the daily npm check for a newer version; see update-check.ts. */
+    updateCheck?: boolean;
+    /** stdio only: which tools to list; undefined lists the default set. See toolsets.ts. */
+    toolsets?: Toolset[];
+    chatgptApp?: {
+        directory: string;
+        previousDirectories?: string[];
+        domain: string;
+        resourceDomains: string[];
+        connectDomains?: string[];
+        uploadStorageOrigin?: string;
+        uploadOrigins?: string[];
+    };
 };
 export declare const DEFAULT_CONFIG: SyncMcpConfig;
 export declare function resolveConfig(overrides?: Partial<SyncMcpConfig>): SyncMcpConfig;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,aAI5B,CAAC;AAEF,wBAAgB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CAOnF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAG5D,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,4FAA4F;IAC5F,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,EAAE,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,aAI5B,CAAC;AAkCF,wBAAgB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CAgCnF"}

package/dist/config.js

@@ -1,13 +1,65 @@
+import { z } from 'zod';
+import { resolveChatgptRelease } from './chatgpt-release.js';
+import { parseSpendConfirmation } from './spend-confirmation.js';
+import { parseToolsets } from './toolsets.js';
+import { parseUpdateCheck } from './update-check.js';
 export const DEFAULT_CONFIG = {
     baseUrl: 'https://api.sync.so',
     transport: 'stdio',
     port: 3002,
 };
+const OAuthAuthorizationUrlSchema = z
+    .url()
+    .refine((value) => {
+    const url = new URL(value);
+    return ((url.protocol === 'https:' || url.protocol === 'http:') &&
+        !url.username &&
+        !url.password &&
+        !url.search &&
+        !url.hash);
+}, 'OAuth authorization URL must use HTTP(S) without credentials, query or fragment')
+    .optional();
+/** The ChatGPT UI release to serve, from the release catalog or the legacy directory settings. */
+function resolveChatgptAppRelease() {
+    const legacyDirectory = process.env.SYNC_CHATGPT_APP_DIR;
+    const catalogPath = process.env.SYNC_CHATGPT_APP_RELEASES;
+    if (!legacyDirectory && !(catalogPath && process.env.SYNC_CHATGPT_APP_DOMAIN))
+        return undefined;
+    const previous = z
+        .array(z.string().min(1))
+        .parse(JSON.parse(process.env.SYNC_CHATGPT_APP_PREVIOUS_DIRS ?? '[]'));
+    return catalogPath
+        ? resolveChatgptRelease(catalogPath, [
+            ...previous,
+            ...(legacyDirectory ? [legacyDirectory] : []),
+        ])
+        : { directory: legacyDirectory, previousDirectories: previous };
+}
 export function resolveConfig(overrides = {}) {
+    const release = overrides.chatgptApp ? undefined : resolveChatgptAppRelease();
     return {
         apiKey: overrides.apiKey ?? process.env.SYNC_API_KEY,
         baseUrl: overrides.baseUrl ?? process.env.SYNC_BASE_URL ?? DEFAULT_CONFIG.baseUrl,
+        oauthAuthorizationUrl: OAuthAuthorizationUrlSchema.parse(overrides.oauthAuthorizationUrl ?? process.env.SYNC_OAUTH_AUTHORIZATION_URL),
         transport: overrides.transport ?? DEFAULT_CONFIG.transport,
         port: overrides.port ?? DEFAULT_CONFIG.port,
+        spendConfirmation: overrides.spendConfirmation ??
+            parseSpendConfirmation(process.env.SYNC_MCP_SPEND_CONFIRMATION) ??
+            true,
+        updateCheck: overrides.updateCheck ?? parseUpdateCheck(process.env.SYNC_MCP_UPDATE_CHECK) ?? true,
+        toolsets: overrides.toolsets ?? parseToolsets(process.env.SYNC_MCP_TOOLSETS),
+        chatgptApp: overrides.chatgptApp ??
+            (release
+                ? {
+                    ...release,
+                    domain: process.env.SYNC_CHATGPT_APP_DOMAIN ?? '',
+                    uploadStorageOrigin: process.env.SYNC_APP_UPLOAD_STORAGE_ORIGIN,
+                    uploadOrigins: process.env.SYNC_APP_UPLOAD_ORIGINS
+                        ? JSON.parse(process.env.SYNC_APP_UPLOAD_ORIGINS)
+                        : undefined,
+                    connectDomains: JSON.parse(process.env.SYNC_CHATGPT_APP_CONNECT_DOMAINS ?? '[]'),
+                    resourceDomains: JSON.parse(process.env.SYNC_CHATGPT_APP_RESOURCE_DOMAINS ?? '[]'),
+                }
+                : undefined),
     };
 }

package/dist/generation-status-html.d.ts

@@ -0,0 +1,2 @@
+export declare const GENERATION_STATUS_HTML: string;
+//# sourceMappingURL=generation-status-html.d.ts.map

package/dist/generation-status-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-status-html.d.ts","sourceRoot":"","sources":["../src/generation-status-html.ts"],"names":[],"mappings":"AA4BA,eAAO,MAAM,sBAAsB,QAAwB,CAAC"}

package/dist/generation-status-html.js

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { gunzipSync } from 'node:zlib';
+import { z } from 'zod';
+// Built from the companion workspace's real @sync/ui components and brand tokens.
+const directory = new URL('../deploy/generation-status/', import.meta.url);
+const release = z
+    .object({
+    repository: z.literal('synchronicity-labs/sync-api-v2'),
+    commit: z.string().regex(/^[a-f0-9]{40}$/),
+    htmlSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    htmlBytes: z
+        .number()
+        .int()
+        .positive()
+        .max(8 * 1024 * 1024),
+})
+    .parse(JSON.parse(readFileSync(new URL('release.json', directory), 'utf8')));
+const html = gunzipSync(readFileSync(new URL('app.html.gz', directory)), {
+    maxOutputLength: 8 * 1024 * 1024,
+});
+if (html.length !== release.htmlBytes ||
+    createHash('sha256').update(html).digest('hex') !== release.htmlSha256) {
+    throw new Error('Generation status UI does not match its approved release.');
+}
+export const GENERATION_STATUS_HTML = html.toString('utf8');

package/dist/generation-status.d.ts

@@ -0,0 +1,6 @@
+import type { ResourceMetadata } from '@modelcontextprotocol/server';
+import type { McpToolDefinition } from './tools/generator.js';
+export declare const GENERATION_STATUS_URI = "ui://sync/generation-status-v1.html";
+export declare function withGenerationStatusCard(tool: McpToolDefinition): McpToolDefinition;
+export declare const GENERATION_STATUS_METADATA: ResourceMetadata;
+//# sourceMappingURL=generation-status.d.ts.map

package/dist/generation-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generation-status.d.ts","sourceRoot":"","sources":["../src/generation-status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,eAAO,MAAM,qBAAqB,wCAAwC,CAAC;AAU3E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAanF;AAID,eAAO,MAAM,0BAA0B,EAAE,gBAUxC,CAAC"}

package/dist/generation-status.js

@@ -0,0 +1,37 @@
+import { MCP_APP_RESOURCE_MIME_TYPE } from './tools/upload-widget.js';
+export const GENERATION_STATUS_URI = 'ui://sync/generation-status-v1.html';
+const submissionTools = new Set([
+    'lipsync_create',
+    'lipsync_create-from-assets',
+    'lipsync_create-timeline',
+    'dubbing_create',
+    'dialogue-videos_create',
+    'generations_create',
+]);
+export function withGenerationStatusCard(tool) {
+    if (!submissionTools.has(tool.name))
+        return tool;
+    return {
+        ...tool,
+        meta: {
+            ...tool.meta,
+            ui: {
+                ...tool.meta?.ui,
+                resourceUri: GENERATION_STATUS_URI,
+            },
+            'openai/outputTemplate': GENERATION_STATUS_URI,
+        },
+    };
+}
+const description = 'Status of this Sync generation, with estimated time remaining and a read-only Check status action.';
+export const GENERATION_STATUS_METADATA = {
+    title: 'Sync generation status',
+    description,
+    mimeType: MCP_APP_RESOURCE_MIME_TYPE,
+    _meta: {
+        ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: ['data:'] } },
+        'openai/widgetDescription': description,
+        'openai/widgetPrefersBorder': true,
+        'openai/widgetCSP': { connect_domains: [], resource_domains: ['data:'] },
+    },
+};

package/dist/http-client.d.ts

@@ -1,11 +1,55 @@
+import { z } from 'zod';
+export declare function resolveSyncSource(clientName?: string): string;
+export declare const UPSTREAM_REQUEST_TIMEOUT_MS = 65000;
+declare const importErrorDetailsSchema: z.ZodObject<{
+    importJobId: z.ZodOptional<z.ZodUUID>;
+    importStatus: z.ZodOptional<z.ZodEnum<{
+        completed: "completed";
+        downloading: "downloading";
+        failed: "failed";
+        processing: "processing";
+        queued: "queued";
+    }>>;
+    progress: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const errorDetailsSchema: z.ZodObject<{
+    requiredPlan: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    billingUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    activeBatches: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    concurrencyLimit: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    lineNumber: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type ApiErrorDetails = z.infer<typeof errorDetailsSchema>;
+export declare class ApiRequestError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
+    readonly generationId?: string | undefined;
+    readonly importDetails?: z.infer<typeof importErrorDetailsSchema> | undefined;
+    readonly details?: ApiErrorDetails | undefined;
+    /** Set by a tool that knows a better next step than the generic one for this code. */
+    nextStep?: string;
+    /** The API's own advice for this error code, when the response carries one. */
+    suggestion?: string;
+    constructor(message: string, status: number, code?: string | undefined, retryAfterMs?: number | undefined, generationId?: string | undefined, importDetails?: z.infer<typeof importErrorDetailsSchema> | undefined, details?: ApiErrorDetails | undefined);
+}
+export declare function cameFromApi(error: unknown): boolean;
 type AuthHeaders = Record<string, string>;
 export type HttpClient = {
     request: (method: string, path: string, options?: {
         query?: Record<string, string>;
         body?: unknown;
         headers?: Record<string, string>;
+        signal?: AbortSignal;
     }) => Promise<unknown>;
 };
-export declare function createHttpClient(baseUrl: string, authHeaders: AuthHeaders): HttpClient;
+/**
+ * Creates an HTTP client for the Sync API.
+ *
+ * Auth is resolved in this order:
+ * 1. Per-request token from AsyncLocalStorage (set by OAuth middleware in HTTP transport)
+ * 2. Static auth headers (API key or device auth token, set at startup for stdio transport)
+ */
+export declare function createHttpClient(baseUrl: string, staticAuthHeaders?: AuthHeaders, stdioClientName?: () => string | undefined): HttpClient;
 export {};
 //# sourceMappingURL=http-client.d.ts.map

package/dist/http-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAEA,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1C,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,CACP,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,KACE,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,UAAU,CAkDtF"}
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7D;AAuBD,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,QAAA,MAAM,wBAAwB;;;;;;;;;;iBAI5B,CAAC;AAIH,QAAA,MAAM,kBAAkB;;;;;;iBAMtB,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEjE,qBAAa,eAAgB,SAAQ,KAAK;IAQtC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe;IAZpC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,YAAY,CAAC,EAAE,MAAM,YAAA,EACrB,YAAY,CAAC,EAAE,MAAM,YAAA,EACrB,aAAa,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,YAAA,EACxD,OAAO,CAAC,EAAE,eAAe,YAAA,EAInC;CACF;AAmBD,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1C,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,CACP,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,KACE,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,iBAAiB,GAAE,WAAgB,EACnC,eAAe,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GACzC,UAAU,CAuGZ"}

package/dist/http-client.js

@@ -1,43 +1,180 @@
-const SYNC_SOURCE = 'mcp';
-export function createHttpClient(baseUrl, authHeaders) {
+import { z } from 'zod';
+import { combineSignals } from './abort-signals.js';
+import { getAuthToken, getClientName } from './auth/async-context.js';
+import { chosenOrganization, ORGANIZATION_HEADER } from './organization-selection.js';
+import { getToolAnalytics } from './tool-analytics-context.js';
+import { PACKAGE_VERSION } from './version.js';
+/** API-key analytics labels; bearer credentials use the API's MCP source namespace. */
+const FIRST_CLASS_SOURCE_BY_CLIENT = {
+    chatgpt: 'chatgpt',
+    openai: 'chatgpt',
+    'openai-chatgpt': 'chatgpt',
+    claude: 'claude',
+    'claude-ai': 'claude',
+    gemini: 'gemini',
+    google: 'gemini',
+};
+export function resolveSyncSource(clientName) {
+    if (!clientName)
+        return 'mcp';
+    return FIRST_CLASS_SOURCE_BY_CLIENT[clientName.toLowerCase()] ?? `mcp:${clientName}`;
+}
+/**
+ * Who is calling: the analytics source, this server's version and the MCP client's
+ * handshake name when known. The API ignores headers it does not record.
+ */
+function clientHeaders(authHeaders, clientName) {
+    const syncSource = authHeaders.Authorization?.startsWith('Bearer ')
+        ? clientName
+            ? `mcp:${clientName}`
+            : 'mcp'
+        : resolveSyncSource(clientName);
+    return {
+        'x-sync-source': syncSource,
+        'x-sync-mcp-version': PACKAGE_VERSION,
+        ...(clientName ? { 'x-sync-mcp-client': clientName } : {}),
+    };
+}
+// Bound upstream calls independently of the API-defined polling window. No write retries.
+export const UPSTREAM_REQUEST_TIMEOUT_MS = 65_000;
+const importErrorDetailsSchema = z.object({
+    importJobId: z.uuid().optional(),
+    importStatus: z.enum(['queued', 'downloading', 'processing', 'completed', 'failed']).optional(),
+    progress: z.number().min(0).max(100).optional(),
+});
+// Error fields worth showing the agent as they are: what a refusal needs (a 402's plan and
+// billing page), a batch limit's counts, and the line a batch refusal points at.
+const errorDetailsSchema = z.object({
+    requiredPlan: z.string().optional().catch(undefined),
+    billingUrl: z.string().optional().catch(undefined),
+    activeBatches: z.number().optional().catch(undefined),
+    concurrencyLimit: z.number().optional().catch(undefined),
+    lineNumber: z.number().int().positive().optional().catch(undefined),
+});
+export class ApiRequestError extends Error {
+    status;
+    code;
+    retryAfterMs;
+    generationId;
+    importDetails;
+    details;
+    /** Set by a tool that knows a better next step than the generic one for this code. */
+    nextStep;
+    /** The API's own advice for this error code, when the response carries one. */
+    suggestion;
+    constructor(message, status, code, retryAfterMs, generationId, importDetails, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.generationId = generationId;
+        this.importDetails = importDetails;
+        this.details = details;
+        this.name = 'ApiRequestError';
+    }
+}
+// The API's advice for a coded error, such as reconnecting to grant an organization.
+function apiSuggestion(parsed) {
+    return z.object({ suggestion: z.string() }).safeParse(parsed).data?.suggestion;
+}
+function errorDetails(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const details = errorDetailsSchema.parse(parsed);
+    const present = Object.fromEntries(Object.entries(details).filter(([, value]) => value !== undefined));
+    return Object.keys(present).length > 0 ? present : undefined;
+}
+// Errors built from an API response, as opposed to this server's own checks.
+const apiResponseErrors = new WeakSet();
+export function cameFromApi(error) {
+    return error instanceof ApiRequestError && apiResponseErrors.has(error);
+}
+/**
+ * Creates an HTTP client for the Sync API.
+ *
+ * Auth is resolved in this order:
+ * 1. Per-request token from AsyncLocalStorage (set by OAuth middleware in HTTP transport)
+ * 2. Static auth headers (API key or device auth token, set at startup for stdio transport)
+ */
+export function createHttpClient(baseUrl, staticAuthHeaders = {}, stdioClientName) {
     return {
         async request(method, path, options = {}) {
-            const url = new URL(path, baseUrl);
-            if (options.query) {
-                for (const [key, value] of Object.entries(options.query)) {
-                    if (value !== undefined && value !== '') {
-                        url.searchParams.set(key, value);
+            const deadline = AbortSignal.timeout(UPSTREAM_REQUEST_TIMEOUT_MS);
+            const { signal, dispose } = combineSignals(options.signal ? [options.signal, deadline] : [deadline]);
+            try {
+                signal.throwIfAborted();
+                const url = new URL(path.replace(/^\//, ''), `${baseUrl.replace(/\/$/, '')}/`);
+                if (options.query) {
+                    for (const [key, value] of Object.entries(options.query)) {
+                        if (value !== undefined && value !== '') {
+                            url.searchParams.set(key, value);
+                        }
                     }
                 }
+                // Per-request OAuth token takes priority over static headers
+                const perRequestToken = getAuthToken();
+                const authHeaders = perRequestToken
+                    ? { Authorization: `Bearer ${perRequestToken}` }
+                    : { ...staticAuthHeaders };
+                const organization = chosenOrganization();
+                const headers = {
+                    ...authHeaders,
+                    ...clientHeaders(authHeaders, getClientName() ?? stdioClientName?.()),
+                    ...(organization ? { [ORGANIZATION_HEADER]: organization.id } : {}),
+                    ...options.headers,
+                    ...(getToolAnalytics() && { 'x-sync-analytics': JSON.stringify(getToolAnalytics()) }),
+                };
+                if (options.body && method !== 'get') {
+                    headers['Content-Type'] = 'application/json';
+                }
+                const response = await fetch(url.toString(), {
+                    method: method.toUpperCase(),
+                    headers,
+                    body: options.body ? JSON.stringify(options.body) : undefined,
+                    signal,
+                });
+                const text = await response.text();
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    parsed = text;
+                }
+                if (!response.ok) {
+                    const message = typeof parsed === 'object' &&
+                        parsed !== null &&
+                        'message' in parsed &&
+                        typeof parsed.message === 'string'
+                        ? parsed.message
+                        : text;
+                    const code = typeof parsed === 'object' &&
+                        parsed !== null &&
+                        'errorCode' in parsed &&
+                        typeof parsed.errorCode === 'string'
+                        ? parsed.errorCode
+                        : undefined;
+                    const retryAfter = response.headers.get('Retry-After');
+                    const seconds = retryAfter === null ? Number.NaN : Number(retryAfter);
+                    const retryAfterMs = Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+                    const knownId = z
+                        .uuid()
+                        .safeParse(parsed && typeof parsed === 'object' && 'generationId' in parsed
+                        ? parsed.generationId
+                        : undefined);
+                    const importDetails = code === 'import_in_progress' || code === 'import_failed'
+                        ? importErrorDetailsSchema.safeParse(parsed)
+                        : undefined;
+                    const error = new ApiRequestError(`API request failed: ${response.status} ${response.statusText} - ${message}`, response.status, code, retryAfterMs, knownId.success ? knownId.data : undefined, importDetails?.success ? importDetails.data : undefined, errorDetails(parsed));
+                    error.suggestion = apiSuggestion(parsed);
+                    apiResponseErrors.add(error);
+                    throw error;
+                }
+                return parsed;
             }
-            const headers = {
-                ...authHeaders,
-                'x-sync-source': SYNC_SOURCE,
-                ...options.headers,
-            };
-            if (options.body && method !== 'get') {
-                headers['Content-Type'] = 'application/json';
-            }
-            const response = await fetch(url.toString(), {
-                method: method.toUpperCase(),
-                headers,
-                body: options.body ? JSON.stringify(options.body) : undefined,
-            });
-            const text = await response.text();
-            let parsed;
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                parsed = text;
-            }
-            if (!response.ok) {
-                const message = typeof parsed === 'object' && parsed !== null && 'message' in parsed
-                    ? parsed.message
-                    : text;
-                throw new Error(`API request failed: ${response.status} ${response.statusText} - ${message}`);
+            finally {
+                dispose();
             }
-            return parsed;
         },
     };
 }

package/dist/http-server.d.ts

@@ -0,0 +1,53 @@
+import { getHeapStatistics } from 'node:v8';
+import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
+import type { McpServer } from '@modelcontextprotocol/server';
+import type { SyncMcpConfig } from './config.js';
+export { extractBasicClientCredentials, mergeBasicClientCredentials, } from './auth/client-credentials.js';
+export declare const OAUTH_PROXY_TIMEOUT_MS = 10000;
+export declare function hasSessionHeapCapacity(heap?: Pick<ReturnType<typeof getHeapStatistics>, 'used_heap_size' | 'heap_size_limit'>): boolean;
+export declare function createSessionHeapAdmission({ readHeap, collect, now, }?: {
+    readHeap?: () => Pick<ReturnType<typeof getHeapStatistics>, 'used_heap_size' | 'heap_size_limit'>;
+    collect?: () => void;
+    now?: () => number;
+}): () => boolean;
+type SessionRuntimeConfig = {
+    idleTtlMs: number;
+    maxSessions: number;
+    maxInFlightRequests: number;
+    sweepIntervalMs: number;
+    shutdownGraceMs: number;
+    telemetryIntervalMs: number;
+};
+export declare function getSessionRuntimeConfig(env?: Record<string, string | undefined>): SessionRuntimeConfig;
+export declare function runSessionSweepSafely(sessions: {
+    sweep: () => Promise<unknown>;
+}, logEvent: (event: string, details: Record<string, unknown>) => void): Promise<void>;
+export declare function sanitizeDiagnosticUrl(value: string): string;
+export declare function createRequestId(value: string | string[] | undefined): string;
+type HttpServerShutdownController = {
+    close: (callback: (error?: Error) => void) => unknown;
+    closeIdleConnections: () => void;
+    closeAllConnections: () => void;
+};
+export declare function closeHttpServerWithGrace(httpServer: HttpServerShutdownController, graceMs: number): Promise<{
+    forced: boolean;
+}>;
+export declare function listenWithCleanup<T>(listen: () => T, waitForStartup: (server: T) => Promise<void>, cleanup: () => void): Promise<T>;
+type HttpServerStartupEmitter = {
+    on: (event: 'error', listener: (error: Error) => void) => unknown;
+    once: (event: 'listening', listener: () => void) => unknown;
+};
+export declare function waitForHttpServerStartup(httpServer: HttpServerStartupEmitter, logEvent: (event: string, details: Record<string, unknown>) => void): Promise<void>;
+/**
+ * Validate browser origins before an HTTP request reaches the MCP transport.
+ * Non-browser MCP clients normally omit Origin, so an absent header is valid.
+ */
+export declare function isAllowedMcpOrigin(origin: string | undefined): boolean;
+export declare function encodeOAuthFormBody(body: Record<string, unknown>): string;
+/** Complete each POST with a JSON response, including large HTML resources. */
+export declare function createHttpMcpTransport(options: ConstructorParameters<typeof NodeStreamableHTTPServerTransport>[0]): NodeStreamableHTTPServerTransport;
+export declare function startHttpServer(serverFactory: {
+    createServer: (clientName?: string, handshakeClientName?: string) => McpServer;
+    toolCount: number;
+}, config: SyncMcpConfig): Promise<void>;
+//# sourceMappingURL=http-server.d.ts.map