@usemo.com/sdk 0.1.0

package/src/cli.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { catalog, downloadAsset, UseMoClient, UseMoError } from './client.js';
+import { profileName, readConfig, writeConfig, resolveConfig, normalizeBase } from './config.js';
+
+const flags = { json: 'boolean', help: 'boolean', version: 'boolean', 'dry-run': 'boolean', wait: 'boolean',
+  'key-stdin': 'boolean', 'base-url': 'string', profile: 'string', data: 'string', out: 'string',
+  'wait-timeout': 'number', 'poll-interval': 'number', timeout: 'number', query: 'string' };
+const short = { j: 'json', h: 'help', v: 'version', p: 'profile', o: 'out' };
+function fieldType(schema, root) {
+  if (schema.$ref) return fieldType(root.$defs[schema.$ref.split('/').at(-1)], root);
+  if (schema.anyOf) return fieldType(schema.anyOf.find(x => x.type !== 'null'), root);
+  return schema.type;
+}
+function parse(argv) {
+  const words = []; const options = {}; const fields = {};
+  // Determine the command before parsing its fields. Global options may precede it.
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token.startsWith('-')) {
+      const key = token.replace(/^--?/, '').split('=')[0];
+      const name = short[key] || key;
+      if (flags[name] && flags[name] !== 'boolean' && !token.includes('=')) i++;
+      else if (!flags[name]) break;
+    } else { words.push(token); if (words.length === 2) break; }
+  }
+  const aliases = { image: 'images', video: 'videos', login: 'auth login', logout: 'auth logout', whoami: 'auth status', use: 'profiles use' };
+  const first = aliases[words[0]] || words[0];
+  let command = first?.includes(' ') ? first : [first, words[1]].filter(Boolean).join(' ');
+  const single = ['schema', 'discover', 'doctor', 'help', 'mcp', 'download'];
+  if (single.includes(words[0])) command = words[0];
+  const tool = catalog.find(x => x.command === command);
+  const localCommands = ['auth login', 'auth logout', 'auth status', 'profiles list', 'profiles use', 'request'];
+  if (words[0] === 'request') command = 'request';
+  const consumed = first?.includes(' ') || single.includes(words[0]) || words[0] === 'request' ? 1 : 2;
+  const positionals = [];
+  let wordIndex = 0;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith('-') || token === '-') { if (wordIndex++ >= consumed) positionals.push(token); continue; }
+    const [raw, ...rest] = token.replace(/^--?/, '').split('=');
+    const key = short[raw] || raw;
+    const field = key.replaceAll('-', '_');
+    const property = tool?.inputSchema.properties[field];
+    const type = flags[key] || (property && fieldType(property, tool.inputSchema));
+    if (!type) throw new UseMoError('invalid_input', `Unknown option ${token}. Run usemo ${command || ''} --help.`);
+    let value = rest.length ? rest.join('=') : type === 'boolean' ? true : argv[++i];
+    if (value === undefined || (typeof value === 'string' && value.startsWith('--'))) throw new UseMoError('invalid_input', `Missing value for --${key}.`);
+    if (type === 'boolean') { if (![true, 'true', 'false'].includes(value)) throw new UseMoError('invalid_input', `--${key} expects true or false.`); value = value === true || value === 'true'; }
+    if (['number', 'integer'].includes(type)) { value = Number(value); if (!Number.isFinite(value)) throw new UseMoError('invalid_input', `--${key} expects a number.`); }
+    if (['array', 'object'].includes(type)) { try { value = JSON.parse(value); } catch { throw new UseMoError('invalid_input', `--${key} expects JSON.`); } }
+    const target = flags[key] ? options : fields;
+    const targetKey = flags[key] ? key : field;
+    if (key === 'query') (options.query ||= []).push(value);
+    else if (Object.hasOwn(target, targetKey)) throw new UseMoError('invalid_input', `Duplicate option --${key}.`);
+    else target[targetKey] = value;
+  }
+  if (!command && (options.help || options.version)) command = 'help';
+  if (command && !tool && !single.includes(command) && !localCommands.includes(command)) throw new UseMoError('invalid_input', `Unknown command: ${command}`);
+  return { command: command || 'help', tool, positionals, options, fields };
+}
+async function stdinText() { let text = ''; for await (const chunk of process.stdin) text += chunk; return text; }
+async function jsonInput(value) {
+  if (!value) return {};
+  try {
+    const text = value === '@-' ? await stdinText() : value.startsWith('@') ? await readFile(value.slice(1), 'utf8') : value;
+    const data = JSON.parse(text);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) throw Error();
+    return data;
+  } catch { throw new UseMoError('invalid_input', '--data must be a JSON object, @file.json, or @- for stdin.'); }
+}
+export function help(tool) {
+  if (tool) return `usemo ${tool.command}${tool.positional ? ' [TEXT_OR_ID]' : ''}\n${tool.description}\n\nFields (also accepted in --data @file.json):\n` +
+    Object.entries(tool.inputSchema.properties).map(([key, value]) => `  --${key.replaceAll('_', '-')}  ${value.description || value.title || ''}`).join('\n') + '\n\nOptions: --json --dry-run --wait --wait-timeout SECONDS --profile NAME --out receipt.json';
+  return `UseMo 0.1.0 — create videos, images and content\n\n` + catalog.map(x => `  ${x.command}`).join('\n') +
+    '\n\n  login --key-stdin | logout | whoami\n  profiles list | profiles use NAME\n  schema [COMMAND] | discover [QUERY] | doctor\n  request METHOD /api/v1/PATH --data JSON --query key=value\n  mcp\n  download HTTPS_URL --out FILE\n\nUse --help on a command for fields. --data accepts JSON, @file, or @-.\n--json emits JSON; --dry-run previews without network; --out saves JSON without overwriting.\nSet USEMO_API_KEY for automation. Run usemo-mcp for MCP stdio.\n';
+}
+async function output(value, options) {
+  const text = typeof value === 'string' && !options.json ? value : JSON.stringify(value, null, options.json ? 0 : 2);
+  if (options.out) await writeFile(options.out, text + '\n', { flag: 'wx', mode: 0o600 });
+  else process.stdout.write(text + '\n');
+}
+export async function main(argv = process.argv.slice(2)) {
+  const { command, tool, positionals, options, fields } = parse(argv);
+  if (options.version) return output({ version: '0.1.0', package: '@usemo.com/sdk' }, options);
+  if (options.help || command === 'help') return output(help(tool), options);
+  if (command === 'schema' || command === 'discover') {
+    const query = positionals.join(' ').toLowerCase();
+    const matches = catalog.filter(x => command === 'schema' ? x.command.includes(query) : query.split(' ').every(w => (x.command + ' ' + x.description).toLowerCase().includes(w)));
+    if (!matches.length) throw new UseMoError('invalid_input', 'No matching command.');
+    return output(matches, options);
+  }
+  if (options.out) {
+    try { await access(options.out); throw new UseMoError('file_exists', 'Output file already exists.'); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+  if (command === 'download') {
+    if (positionals.length !== 1 || !options.out) throw new UseMoError('invalid_input', 'Expected download HTTPS_URL --out FILE.');
+    const receipt = await downloadAsset(positionals[0], options.out, { timeout: options.timeout ?? 120 });
+    return output(receipt, { json: options.json });
+  }
+  if (command === 'mcp') { if (options.out || options.json) throw new UseMoError('invalid_input', 'MCP uses stdout for its protocol.'); const { start } = await import('./mcp.js'); return start(options); }
+  if (command.startsWith('profiles ') || command.startsWith('auth ')) {
+    const config = await readConfig();
+    const name = profileName(options.profile || process.env.USEMO_PROFILE || config.active || 'default');
+    if (command === 'profiles list') return output({ active: config.active, profiles: Object.keys(config.profiles) }, options);
+    if (command === 'profiles use') {
+      if (positionals.length !== 1 || !Object.hasOwn(config.profiles, positionals[0])) throw new UseMoError('invalid_input', 'Choose an existing profile.');
+      config.active = profileName(positionals[0]); await writeConfig(config); return output({ active: config.active }, options);
+    }
+    if (command === 'auth logout') { delete config.profiles[name]; if (config.active === name) config.active = Object.keys(config.profiles)[0] || 'default'; await writeConfig(config); return output({ logged_out: name, revoked: false }, options); }
+    if (command === 'auth login') {
+      if (!options['key-stdin']) throw new UseMoError('invalid_input', 'Provide a key from UseMo Settings → API Keys with usemo login --key-stdin, or set USEMO_API_KEY.');
+      if (options['dry-run']) throw new UseMoError('invalid_input', 'Login does not support --dry-run.');
+      const apiKey = (await stdinText()).trim();
+      if (!apiKey.startsWith('usm_') || /\s/.test(apiKey)) throw new UseMoError('invalid_input', 'Expected a UseMo API key beginning usm_.');
+      const baseUrl = normalizeBase(options['base-url'] || process.env.USEMO_API_BASE);
+      const client = new UseMoClient({ apiKey, baseUrl });
+      await client.run('brand get'); // Verify against a workspace-scoped read before persisting.
+      Object.defineProperty(config.profiles, name, { value: { apiKey, baseUrl }, enumerable: true, configurable: true, writable: true });
+      config.active = name; await writeConfig(config);
+      return output({ authenticated: true, profile: name, base_url: baseUrl }, options);
+    }
+  }
+  const selected = await resolveConfig({ profile: options.profile, baseUrl: options['base-url'] });
+  const client = new UseMoClient({ ...selected, timeout: options.timeout ?? 60 });
+  if (command === 'doctor') return output({ version: '0.1.0', node: process.version, profile: selected.profile, base_url: selected.baseUrl, credential_configured: Boolean(selected.apiKey), commands: catalog.length }, options);
+  if (command === 'auth status') { await client.run('brand get'); return output({ authenticated: true, profile: selected.profile, base_url: selected.baseUrl }, options); }
+  const input = await jsonInput(options.data);
+  for (const [key, value] of Object.entries(fields)) {
+    if (Object.hasOwn(input, key)) throw new UseMoError('invalid_input', `Field ${key} appears in both --data and flags.`);
+    input[key] = value;
+  }
+  if (command === 'request') {
+    if (positionals.length !== 2) throw new UseMoError('invalid_input', 'Expected request METHOD /api/v1/PATH.');
+    const [method, path] = positionals;
+    if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) throw new UseMoError('invalid_input', 'Invalid HTTP method.');
+    if (method === 'GET' && options.data) throw new UseMoError('invalid_input', 'Use --query for GET requests.');
+    const query = {};
+    for (const item of options.query || []) { const i = item.indexOf('='); if (i < 1) throw new UseMoError('invalid_input', '--query expects key=value.'); query[item.slice(0, i)] = item.slice(i + 1); }
+    const body = options.data ? input : undefined;
+    return output(options['dry-run'] ? { dry_run: true, method, path, query, body } : await client.request(method, path, { query, body }), options);
+  }
+  if (positionals.length > (tool.positional ? 1 : 0)) throw new UseMoError('invalid_input', 'Too many positional arguments; quote text containing spaces.');
+  if (positionals.length) {
+    if (Object.hasOwn(input, tool.positional)) throw new UseMoError('invalid_input', `Supply ${tool.positional} once.`);
+    input[tool.positional] = positionals[0];
+  }
+  // Validate polling controls before submitting work that spends credits.
+  const timeout = options['wait-timeout'] ?? 180; const interval = options['poll-interval'] ?? 5;
+  if (!(timeout > 0 && timeout <= 3600 && interval >= 0.1 && interval <= 60)) throw new UseMoError('invalid_input', 'Invalid wait timeout or poll interval.');
+  if (command === 'jobs wait') { if (options['wait-timeout'] !== undefined) input.max_wait_sec = timeout; if (options['poll-interval'] !== undefined) input.poll_interval_sec = interval; }
+  const result = await client.run(command, input, { dryRun: options['dry-run'], wait: options.wait, timeout, interval });
+  await output(result, options);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(resolve(process.argv[1]))).href) {
+  main().catch(error => {
+    const wrapped = error instanceof UseMoError ? error : new UseMoError('local_error', error.code === 'EEXIST' ? 'Output file already exists.' : 'Local operation failed. Check paths and permissions.');
+    process.stderr.write(JSON.stringify({ error: wrapped.toJSON() }) + '\n');
+    process.exitCode = wrapped.code === 'invalid_input' ? 2 : wrapped.code === 'wait_timeout' ? 3 : wrapped.code === 'job_failed' ? 4 : 1;
+  });
+}

package/src/client.js

@@ -0,0 +1,153 @@
+import { readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import { normalizeBase, UseMoError } from './config.js';
+export { UseMoError } from './config.js';
+export const catalog = JSON.parse(readFileSync(new URL('./catalog.json', import.meta.url), 'utf8'));
+const ajv = new Ajv({ strict: false, allErrors: true, useDefaults: true });
+addFormats(ajv);
+const validators = new Map(catalog.map(tool => [tool.name, ajv.compile(tool.inputSchema)]));
+const terminal = new Set(['completed', 'failed', 'cancelled', 'canceled']);
+
+export function prepare(command, input = {}) {
+  const tool = catalog.find(t => t.command === command || t.name === command);
+  if (!tool) throw new UseMoError('invalid_input', `Unknown command or tool: ${command}`);
+  const data = structuredClone(input);
+  if (!validators.get(tool.name)(data)) {
+    throw new UseMoError('invalid_input', `Invalid input for ${tool.command}.`, {
+      validation: validators.get(tool.name).errors.map(({ instancePath, message }) => ({ path: instancePath, message })),
+    });
+  }
+  const key = data.idempotency_key;
+  delete data.idempotency_key;
+  for (const field of Object.keys(data)) if (data[field] === null) delete data[field];
+  let path = tool.path.replace(/\{(\w+)\}/g, (_, field) => {
+    const value = data[field]; delete data[field];
+    if (typeof value !== 'string' || !value.trim() || value === '.' || value === '..') throw new UseMoError('invalid_input', `Invalid ${field}.`);
+    return encodeURIComponent(value);
+  });
+  if (tool.command === 'videos generate') {
+    if (!data.input_image_url && !data.input_image_asset_id) throw new UseMoError('invalid_input', 'Supply a starting image URL or asset ID.');
+    data.input_image = data.input_image_url ? { source_url: data.input_image_url } : { asset_id: data.input_image_asset_id };
+    delete data.input_image_url; delete data.input_image_asset_id;
+  }
+  if (tool.command === 'videos quote' && !data.storyboard && !data.shots?.length) throw new UseMoError('invalid_input', 'Supply a storyboard or shots.');
+  if (tool.command === 'content create') data.delivery_mode = 'auto';
+  if (tool.command === 'jobs wait') { delete data.max_wait_sec; delete data.poll_interval_sec; }
+  return { tool, method: tool.method, path: '/api/v1' + path, ...(tool.method === 'GET' ? { query: data } : { body: data }), ...(key ? { idempotencyKey: key } : {}) };
+}
+function positive(value, name) {
+  if (!Number.isFinite(value) || value <= 0) throw new UseMoError('invalid_input', `${name} must be a positive finite number.`);
+  return value;
+}
+export class UseMoClient {
+  constructor({ apiKey, baseUrl, workspaceId, timeout = 60, fetch: fetchImpl = globalThis.fetch } = {}) {
+    this.apiKey = apiKey; this.baseUrl = normalizeBase(baseUrl); this.workspaceId = workspaceId;
+    this.timeout = positive(timeout, 'timeout'); this.fetch = fetchImpl;
+  }
+  async request(method, path, { body, query = {}, idempotencyKey, timeout = this.timeout, signal } = {}) {
+    if (!this.apiKey) throw new UseMoError('authentication_required', 'Set USEMO_API_KEY or run usemo login --key-stdin.');
+    if (!['GET', 'POST', 'PATCH', 'PUT', 'DELETE'].includes(method)) throw new UseMoError('invalid_input', 'Unsupported HTTP method.');
+    if (!/^\/api\/(?:v1\/)?[a-zA-Z0-9]/.test(path) || /[\\?#]/.test(path) || /%(?:2e|2f|5c)/i.test(path) || path.split('/').some(p => p === '..' || p === '.')) {
+      throw new UseMoError('invalid_input', 'Use a relative /api/v1/... path with query parameters supplied separately.');
+    }
+    const url = new URL(path, this.baseUrl);
+    for (const [k, v] of Object.entries(query)) if (v !== null && v !== undefined) url.searchParams.set(k, String(v));
+    const headers = { Accept: 'application/json', 'X-API-Key': this.apiKey, 'User-Agent': 'usemo-sdk/0.1.0' };
+    if (this.workspaceId) headers['X-Workspace-Id'] = this.workspaceId;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (idempotencyKey) headers['X-Idempotency-Key'] = idempotencyKey;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (signal?.aborted) abort();
+    signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, positive(timeout, 'timeout') * 1000);
+    try {
+      const response = await this.fetch(url, { method, headers, redirect: 'error', signal: controller.signal,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+      const text = await response.text();
+      let data;
+      try { data = text ? JSON.parse(text) : {}; } catch { data = undefined; }
+      if (!response.ok) {
+        const hints = { 401: 'Invalid or expired API key.', 402: 'Insufficient workspace credits.', 403: 'Workspace, scope or plan does not permit this action.', 422: 'Request validation failed.', 429: 'Rate limited; wait before retrying.' };
+        const detail = JSON.stringify(data?.detail ?? data?.error ?? '').replaceAll(this.apiKey, '[redacted]').slice(0, 1000);
+        throw new UseMoError('api_error', hints[response.status] || `UseMo returned HTTP ${response.status}.`, {
+          status: response.status, detail, ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+        });
+      }
+      if (data === undefined) throw new UseMoError('invalid_response', 'UseMo returned a non-JSON response.');
+      return data;
+    } catch (error) {
+      if (error instanceof UseMoError) throw error;
+      throw new UseMoError(controller.signal.aborted ? 'request_timeout' : 'network_error',
+        method === 'GET' ? 'Could not read the UseMo API response.' : 'Submission outcome is unknown. Inspect recent jobs before resubmitting.',
+        { ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}), path });
+    } finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); }
+  }
+  async run(command, input = {}, options = {}) {
+    const plan = prepare(command, input);
+    if (options.dryRun) return { dry_run: true, method: plan.method, path: plan.path, body: plan.body, query: plan.query, idempotency_key: plan.idempotencyKey };
+    if (plan.tool.command === 'jobs wait') return this.wait(input.job_id, { timeout: input.max_wait_sec ?? 180, interval: input.poll_interval_sec ?? 5, signal: options.signal });
+    // Only endpoints verified to implement idempotency receive an automatic key.
+    const supportsKey = Object.hasOwn(plan.tool.inputSchema.properties, 'idempotency_key');
+    if (supportsKey && !plan.idempotencyKey) plan.idempotencyKey = randomUUID();
+    const result = await this.request(plan.method, plan.path, { ...plan, signal: options.signal });
+    const receipt = plan.idempotencyKey ? { ...result, idempotency_key: plan.idempotencyKey } : result;
+    if (options.wait) {
+      const id = result.job_id || result.job?.job_id || result.job?.id;
+      if (id) return { submission: receipt, job: await this.wait(id, options) };
+    }
+    return receipt;
+  }
+  async wait(jobId, { timeout = 180, interval = 5, signal } = {}) {
+    positive(timeout, 'wait timeout'); positive(interval, 'poll interval');
+    if (timeout > 3600 || interval < 0.1) throw new UseMoError('invalid_input', 'Wait timeout must be ≤3600 seconds and poll interval ≥0.1 seconds.');
+    const { path } = prepare('jobs get', { job_id: jobId });
+    const deadline = performance.now() + timeout * 1000;
+    let job;
+    while (performance.now() < deadline) {
+      if (signal?.aborted) throw new UseMoError('cancelled', 'Waiting cancelled; the remote job is still running.', { job_id: jobId });
+      try { job = await this.request('GET', path, { timeout: Math.min(this.timeout, Math.max(0.001, (deadline - performance.now()) / 1000)), signal }); }
+      catch (error) { if (error.code !== 'request_timeout') throw error; break; }
+      if (terminal.has(job.status)) {
+        if (job.status !== 'completed') throw new UseMoError('job_failed', `Job ${jobId} ${job.status}.`, { job_id: jobId, job });
+        return job;
+      }
+      await new Promise(resolve => {
+        const done = () => { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); };
+        const timer = setTimeout(done, Math.max(0, Math.min(interval * 1000, deadline - performance.now())));
+        signal?.addEventListener('abort', done, { once: true });
+      });
+    }
+    throw new UseMoError('wait_timeout', 'Waiting timed out; the remote job was not cancelled. Resume with usemo jobs wait.', { job_id: jobId, job });
+  }
+}
+
+// Downloads are intentionally separate from the authenticated API transport.
+// A CDN must never receive a workspace key, including on redirects.
+export async function downloadAsset(url, destination, { fetch: fetchImpl = globalThis.fetch, timeout = 120 } = {}) {
+  const { createWriteStream } = await import('node:fs');
+  const { link, unlink, access } = await import('node:fs/promises');
+  const { pipeline } = await import('node:stream/promises');
+  const { dirname, join } = await import('node:path');
+  let parsed;
+  try { parsed = new URL(url); } catch { throw new UseMoError('invalid_input', 'Invalid asset URL.'); }
+  if (parsed.protocol !== 'https:' || parsed.username || parsed.password) throw new UseMoError('invalid_input', 'Asset downloads require an HTTPS URL without embedded credentials.');
+  try { await access(destination); throw new UseMoError('file_exists', 'Output file already exists.'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const temporary = join(dirname(destination), `.usemo-${randomUUID()}.part`);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), positive(timeout, 'download timeout') * 1000);
+  try {
+    const response = await fetchImpl(parsed, { redirect: 'error', signal: controller.signal });
+    if (!response.ok || !response.body) throw new UseMoError('download_failed', 'Could not download the asset; refresh its URL from the library.');
+    await pipeline(response.body, createWriteStream(temporary, { flags: 'wx', mode: 0o600 }), { signal: controller.signal });
+    // Atomic no-clobber publication, even if another process creates the target.
+    await link(temporary, destination);
+    return { path: destination, content_type: response.headers.get('content-type') };
+  } catch (error) {
+    if (error instanceof UseMoError) throw error;
+    throw new UseMoError('download_failed', 'Asset transfer failed; no partial destination was written.');
+  } finally { clearTimeout(timer); await unlink(temporary).catch(() => {}); }
+}

package/src/config.js

@@ -0,0 +1,58 @@
+import { chmod, mkdir, readFile, rename, writeFile, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export class UseMoError extends Error {
+  constructor(code, message, details = {}) { super(message); this.code = code; this.details = details; }
+  toJSON() { return { code: this.code, message: this.message, ...this.details }; }
+}
+export function normalizeBase(value = 'https://api.usemo.com') {
+  let url;
+  try { url = new URL(value); } catch { throw new UseMoError('invalid_input', 'Invalid API base URL.'); }
+  if (url.username || url.password || url.search || url.hash ||
+      !(url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
+    throw new UseMoError('invalid_input', 'API base must use HTTPS (HTTP is allowed on loopback only), without credentials, query or fragment.');
+  }
+  if (!['', '/', '/api', '/api/', '/api/v1', '/api/v1/'].includes(url.pathname)) {
+    throw new UseMoError('invalid_input', 'API base must be an origin, optionally ending in /api or /api/v1.');
+  }
+  return url.origin;
+}
+export const configDir = (env = process.env) => env.USEMO_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'usemo');
+export async function readConfig(env = process.env) {
+  try {
+    const config = JSON.parse(await readFile(join(configDir(env), 'config.json'), 'utf8'));
+    if (config.version !== 1 || !config.profiles || typeof config.profiles !== 'object' || Array.isArray(config.profiles)) throw Error();
+    return config;
+  } catch (error) {
+    if (error.code === 'ENOENT') return { version: 1, active: 'default', profiles: {} };
+    throw new UseMoError('config_error', 'Cannot read UseMo config.json. Repair it before continuing.');
+  }
+}
+export async function writeConfig(config, env = process.env) {
+  const dir = configDir(env);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+  const temporary = join(dir, `.config-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, JSON.stringify(config, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+    await rename(temporary, join(dir, 'config.json'));
+  } finally { await unlink(temporary).catch(() => {}); }
+}
+export function profileName(name) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$/.test(name)) throw new UseMoError('invalid_input', 'Profile names must be 1–64 letters, digits, dots, dashes or underscores.');
+  return name;
+}
+export async function resolveConfig(options = {}, env = process.env) {
+  const config = await readConfig(env);
+  const name = profileName(options.profile || env.USEMO_PROFILE || config.active || 'default');
+  const profile = Object.hasOwn(config.profiles, name) ? config.profiles[name] : {};
+  const apiKey = env.USEMO_API_KEY || profile.apiKey;
+  const baseUrl = normalizeBase(options.baseUrl || env.USEMO_API_BASE || profile.baseUrl);
+  // Saved credentials are bound to the host where they were registered.
+  if (!env.USEMO_API_KEY && apiKey && baseUrl !== normalizeBase(profile.baseUrl)) {
+    throw new UseMoError('credential_origin_mismatch', 'This profile belongs to a different API host. Log in to a separate profile or explicitly provide USEMO_API_KEY.');
+  }
+  return { apiKey, baseUrl, profile: name, workspaceId: env.USEMO_WORKSPACE_ID || profile.workspaceId };
+}

package/src/mcp.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { catalog, UseMoClient, UseMoError } from './client.js';
+import { resolveConfig } from './config.js';
+
+export function createServer(client) {
+  const server = new Server({ name: 'usemo', version: '0.1.0' }, { capabilities: { tools: {} },
+    instructions: 'UseMo creates videos, images and content. Discover tools, read brand context, plan/quote, then create and poll jobs. Creation spends workspace credits. A timeout does not cancel a job. Do not blindly resubmit. Use the same idempotency_key after an uncertain submission when the tool supports it.' });
+  const discovery = [
+    { name: 'usemo_get_started', description: 'Get UseMo setup and workflow guidance without accessing workspace data.', inputSchema: { type: 'object', properties: {}, additionalProperties: false }, annotations: { readOnlyHint: true, openWorldHint: false } },
+    { name: 'usemo_discover_tools', description: 'Search available UseMo tools and schemas by name or description. Offline.', inputSchema: { type: 'object', properties: { query: { type: 'string' } }, additionalProperties: false }, annotations: { readOnlyHint: true, openWorldHint: false } },
+  ];
+  const tools = [...discovery, ...catalog.map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations }))];
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    try {
+      const { name, arguments: args = {} } = request.params;
+      let result;
+      if (name === 'usemo_get_started') result = { workflow: 'brand → plan/quote → create → jobs wait → asset URL', cli: 'usemo --help', credentials: 'USEMO_API_KEY or usemo login --key-stdin', commands: catalog.map(x => x.command) };
+      else if (name === 'usemo_discover_tools') {
+        if (args.query !== undefined && typeof args.query !== 'string') throw new UseMoError('invalid_input', 'query must be a string.');
+        const words = (args.query || '').toLowerCase().split(/\s+/);
+        result = { tools: tools.filter(t => words.every(w => (t.name + ' ' + t.description).toLowerCase().includes(w))) };
+      } else {
+        result = await client.run(name, args, { signal: extra.signal });
+        // Hosted MCP exposes a compact workflow envelope; retain that contract
+        // while keeping the CLI/JS API's original REST responses intact.
+        if (name === 'usemo_create_video' && result.job) {
+          result = { ...result, job_id: result.job.job_id || result.job.id, status: result.job.status, job_path: result.job.job_path };
+        }
+        if (name === 'usemo_generate_content' && result.job) {
+          result = { ...result, job_id: result.job.job_id || result.job.id, status: result.job.status || 'queued', job_path: result.job.job_path };
+        }
+        const listKey = { usemo_list_jobs: 'jobs', usemo_list_assets: 'assets', usemo_list_twins: 'twins' }[name];
+        if (listKey && Array.isArray(result)) result = { [listKey]: result, count: result.length };
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    } catch (error) {
+      const safe = error instanceof UseMoError ? error.toJSON() : { code: 'internal_error', message: 'UseMo tool failed.' };
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: safe }) }] };
+    }
+  });
+  return server;
+}
+export async function start(options = {}) {
+  const client = new UseMoClient(await resolveConfig({ profile: options.profile, baseUrl: options['base-url'] }));
+  const server = createServer(client);
+  await server.connect(new StdioServerTransport());
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(resolve(process.argv[1]))).href) start().catch(() => { process.stderr.write('UseMo MCP could not start. Check local configuration.\n'); process.exitCode = 1; });