@vidofy/mcp 0.1.0

package/dist/config.js

@@ -0,0 +1,207 @@
+/**
+ * Where the server points, and which credential it carries.
+ *
+ * ONE credential, ONE door — never both. The two modes bill different wallets:
+ *
+ *   VIDOFY_TOKEN   (vmt_…)  → the user's own coins      (account mode — served)
+ *   VIDOFY_API_KEY (vky_…)  → a different balance       (key mode — refused)
+ *
+ * Mixing them would mean a caller could not tell which balance a generation
+ * was going to spend until after it spent it, so a request carrying both is
+ * refused at startup rather than resolved by precedence.
+ *
+ * Key mode is DETECTED but NOT SERVED, and that is the settled shape of the
+ * product rather than a gap (owner decision, 2026-09-11): this server is for
+ * personal Vidofy accounts and spends their own coins. It is detected only so
+ * that a key can be refused with an explanation instead of failing later as an
+ * unexplained 401.
+ *
+ * Detected rather than ignored so that someone who sets VIDOFY_API_KEY is told
+ * where to go, instead of watching the server start and then fail on every
+ * call. See the refusal in index.ts.
+ */
+export class ConfigError extends Error {
+}
+const DEFAULT_BASE = 'https://vidofy.ai';
+/**
+ * Read the environment into a Config, or throw a message a human can act on.
+ *
+ * @param env  Defaults to process.env; injectable so this is testable without
+ *             mutating the real environment.
+ */
+export function loadConfig(env = process.env, version = '0.0.0') {
+    const token = (env['VIDOFY_TOKEN'] ?? '').trim();
+    const apiKey = (env['VIDOFY_API_KEY'] ?? '').trim();
+    if (token !== '' && apiKey !== '') {
+        throw new ConfigError('Both VIDOFY_TOKEN and VIDOFY_API_KEY are set. They bill different balances — ' +
+            'your personal coins and the API credit wallet — so pick one and remove the other.');
+    }
+    if (token === '' && apiKey === '') {
+        throw new ConfigError('No credential. Set VIDOFY_TOKEN to a personal MCP token from ' +
+            'https://vidofy.ai/en/studio/account/mcp-tokens (this bills your own Vidofy coins).');
+    }
+    const mode = token !== '' ? 'account' : 'key';
+    const credential = token !== '' ? token : apiKey;
+    /* Catch a swapped credential HERE rather than as a 401 on the first call.
+       The prefixes are the server's own: vmt_ for a personal MCP token,
+       vky_ for a partner API key. */
+    if (mode === 'account' && !credential.startsWith('vmt_')) {
+        throw new ConfigError('VIDOFY_TOKEN does not look like a personal MCP token (they start with "vmt_"). ' +
+            (credential.startsWith('vky_')
+                ? 'That looks like an API key — set it as VIDOFY_API_KEY instead.'
+                : 'Create one at https://vidofy.ai/en/studio/account/mcp-tokens'));
+    }
+    if (mode === 'key' && !credential.startsWith('vky_')) {
+        throw new ConfigError('VIDOFY_API_KEY does not look like an API key (they start with "vky_"). ' +
+            (credential.startsWith('vmt_')
+                ? 'That looks like a personal MCP token — set it as VIDOFY_TOKEN instead.'
+                : 'Find yours in the API platform on vidofy.ai'));
+    }
+    return {
+        mode,
+        credential,
+        baseUrl: resolveBaseUrl(env),
+        version,
+        // Recorded server-side against the request in key mode and against the
+        // token in account mode, which is how "how much traffic came from MCP"
+        // is answered without any new tracking.
+        userAgent: `vidofy-mcp/${version}`,
+    };
+}
+/**
+ * A Config for ONE `vmt_` token, with the origin still taken from the process
+ * environment.
+ *
+ * This exists for the remote transport, where the two halves of a Config arrive
+ * from different places and at different times: the origin is server
+ * configuration, fixed at boot, while the credential belongs to whoever is
+ * making this particular request. loadConfig cannot serve that case — it reads
+ * the credential from the environment, which in a multi-user process would mean
+ * every caller spending one account's coins.
+ *
+ * The prefix check is deliberately the SAME one loadConfig applies. A remote
+ * caller pasting `vky_` into an Authorization header deserves the answer the
+ * local user gets, not a 401 that says nothing.
+ *
+ * @throws ConfigError — the caller turns it into a 401 with a readable message.
+ */
+export function configForToken(token, env = process.env, version = '0.0.0', resource) {
+    const credential = token.trim();
+    if (credential === '') {
+        throw new ConfigError('No bearer token. Send Authorization: Bearer vmt_… with every request.');
+    }
+    if (!credential.startsWith('vmt_')) {
+        throw new ConfigError(credential.startsWith('vky_')
+            /* No full stop after either URL. A terminal that auto-links takes the
+               trailing period as part of the href, and the user clicks through to
+               a 404 — from a message whose whole job was to get them to that page. */
+            ? 'That is an API key (vky_…). This connector serves personal Vidofy accounts and bills '
+                + 'your own coins — set VIDOFY_TOKEN (vmt_…) instead, from '
+                + 'https://vidofy.ai/en/studio/account/mcp-tokens'
+            : 'Not a personal MCP token. They start with "vmt_" — create one at '
+                + 'https://vidofy.ai/en/studio/account/mcp-tokens');
+    }
+    return {
+        mode: 'account',
+        credential,
+        baseUrl: resolveBaseUrl(env),
+        version,
+        userAgent: `vidofy-mcp/${version}`,
+        ...(resource !== undefined && resource !== '' ? { resource } : {}),
+    };
+}
+/**
+ * Validate and normalise VIDOFY_API_BASE.
+ *
+ * Factored out of loadConfig so the remote transport cannot end up with a
+ * weaker check than the local one — the checks below are the whole reason a
+ * hostile value in claude_desktop_config.json cannot redirect a credential, and
+ * a second copy of them would be a second chance to get one wrong.
+ */
+export function resolveBaseUrl(env = process.env) {
+    // VIDOFY_API_BASE exists for development against a local instance. Trailing
+    // slashes are stripped so callers can join paths without doubling them.
+    const baseUrl = ((env['VIDOFY_API_BASE'] ?? '').trim() || DEFAULT_BASE).replace(/\/+$/, '');
+    if (!/^https?:\/\//i.test(baseUrl)) {
+        throw new ConfigError(`VIDOFY_API_BASE must start with http:// or https:// — got "${baseUrl}"`);
+    }
+    /* The scheme check alone is not a check.
+     *
+     * This value is set in claude_desktop_config.json, which people copy and
+     * paste from install snippets they found somewhere — so it is exactly the
+     * field a hostile snippet would target, and the credential goes wherever it
+     * points. Measured, all of these passed the scheme test:
+     *
+     *   https://vidofy.ai@evil.example  → host is evil.example; the token ships there
+     *   http://vidofy.ai                → the vmt_ token crosses the network in clear
+     *   https://vidofy.ai/#             → every path lands on the homepage instead
+     *   https://vidofy.ai?x=1           → same, and nothing says why
+     *
+     * The last two are not attacks, just silent breakage — which is worse to
+     * diagnose than a refusal at startup. */
+    let parsedBase;
+    try {
+        parsedBase = new URL(baseUrl);
+    }
+    catch {
+        throw new ConfigError(`VIDOFY_API_BASE is not a valid URL — got "${baseUrl}"`);
+    }
+    if (parsedBase.username !== '' || parsedBase.password !== '') {
+        throw new ConfigError(`VIDOFY_API_BASE must not contain a username or password. In "${baseUrl}" the real ` +
+            `host is "${parsedBase.host}", not what appears before the "@".`);
+    }
+    /* Tested on the RAW string, not on the parsed parts: a bare "#" produces
+       an empty `hash`, so `parsedBase.hash !== ''` waves through
+       "https://vidofy.ai/#" — which then swallows every path appended to it
+       and sends the whole API to the homepage. */
+    /* Whitespace is rejected on the RAW string too. WHATWG URL silently strips
+       a newline, so "https://vidofy.ai\nevil" parses as host `vidofy.aievil`
+       while the value a user skims in claude_desktop_config.json still reads
+       as vidofy.ai — the same smuggling this block exists to stop. */
+    if (/\s/.test(baseUrl)) {
+        throw new ConfigError('VIDOFY_API_BASE must not contain whitespace or line breaks.');
+    }
+    if (/[?#]/.test(baseUrl) || parsedBase.pathname !== '/') {
+        throw new ConfigError(`VIDOFY_API_BASE must be an origin only — no path, query or fragment. Got "${baseUrl}".`);
+    }
+    /* URL.hostname keeps the brackets on an IPv6 literal — `new URL('http://[::1]')`
+       gives '[::1]', not '::1' — so comparing against the bare form refused
+       IPv6 loopback although it is listed right here as allowed. Strip them
+       once and compare. `.localhost` and `.test` are RFC 6761 loopback/testing
+       names, and host.docker.internal is how a container reaches this host;
+       all three are development, none reaches the internet. */
+    const host = parsedBase.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    const localHost = host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '::1' ||
+        host === 'host.docker.internal' ||
+        host.endsWith('.local') ||
+        host.endsWith('.localhost') ||
+        host.endsWith('.test');
+    if (parsedBase.protocol !== 'https:' && !localHost) {
+        throw new ConfigError(`VIDOFY_API_BASE must use https:// — "${baseUrl}" would send your credential in clear text. ` +
+            'Plain http is accepted only for localhost and .local development hosts.');
+    }
+    // The parsed origin, not the raw string — so whatever survived the checks
+    // above is still normalised to scheme://host[:port] before anything
+    // concatenates a path onto it.
+    return parsedBase.origin;
+}
+/** The credential header for this mode. Kept next to loadConfig so the two cannot drift. */
+export function authHeaders(cfg) {
+    const creds = cfg.mode === 'account'
+        ? { Authorization: `Bearer ${cfg.credential}` }
+        : { 'X-API-Key': cfg.credential };
+    /* The audience travels with the credential because it is part of deciding
+       whether the credential is valid HERE — see Config.resource. Omitted
+       entirely when there is none, since an empty header and no header are the
+       same thing to the reader but not to a proxy. */
+    return cfg.resource !== undefined && cfg.resource !== ''
+        ? { ...creds, 'X-Vidofy-MCP-Resource': cfg.resource }
+        : creds;
+}
+/** `/app/v1` or `/api/v1` — the door this mode speaks to. */
+export function apiPrefix(cfg) {
+    return cfg.mode === 'account' ? '/app/v1' : '/api/v1';
+}
+//# sourceMappingURL=config.js.map

package/dist/heartbeat.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Start reporting liveness. Safe to call twice; the second call does nothing.
+ *
+ * Failure here must never take the connector down — it is a report, not the
+ * work. But it must not be silent either, because a silent failure looks exactly
+ * like a dead process on the dashboard and would send someone to restart a
+ * server that was serving traffic the whole time. So the first failure logs, and
+ * the rest do not (a Redis outage would otherwise write a line every 30s
+ * forever).
+ */
+export declare function startHeartbeat(): void;

package/dist/heartbeat.js

@@ -0,0 +1,70 @@
+/**
+ * Liveness reporting, for the operator's own process dashboard.
+ *
+ * WHY THIS EXISTS. The remote connector runs as a long-lived managed process,
+ * and every such process on this platform is expected to report that it is
+ * alive. The dashboard does not interrogate the process manager — it reads a
+ * key the program writes for itself. A program that is registered and writes
+ * nothing therefore shows as **down forever** and raises a CRITICAL alert on a
+ * process that is perfectly healthy, which is worse than not registering it at
+ * all: the one alert nobody can act on is the one that teaches people to ignore
+ * the page.
+ *
+ * The contract is the same one every other worker on the platform writes, and
+ * the platform is the reference if the two ever disagree:
+ *
+ *   value the unix timestamp, as a decimal string
+ *   TTL   300s — deliberately longer than the dashboard's 120s down window, so a
+ *         healthy program's key never expires between writes. Down-detection
+ *         compares the STORED timestamp, not key presence, so an expired key and
+ *         a stale one read the same.
+ *   every 30s
+ *
+ * The `cache:` prefix is correct here, unlike `mcp_oauth:`: this value is a
+ * report about something else, so an operator clearing the cache erases one
+ * 30-second window and no state. A pending authorization erased would cost a
+ * user their sign-in, which is why that one sits outside the prefix.
+ */
+import { redisClient } from './oauth/store.js';
+import { log } from './log.js';
+/** Matches the platform's own workers. The dashboard's window is 120s. */
+const INTERVAL_MS = 30_000;
+const TTL_SEC = 300;
+/** The managed-process name — this IS the dashboard's key, so it must match. */
+const PROGRAM = 'vidofy-mcp';
+let timer = null;
+let warned = false;
+async function beat() {
+    const client = await redisClient();
+    await client.setEx(`cache:scheduled_tasks:hb:${PROGRAM}`, TTL_SEC, String(Math.floor(Date.now() / 1000)));
+}
+/**
+ * Start reporting liveness. Safe to call twice; the second call does nothing.
+ *
+ * Failure here must never take the connector down — it is a report, not the
+ * work. But it must not be silent either, because a silent failure looks exactly
+ * like a dead process on the dashboard and would send someone to restart a
+ * server that was serving traffic the whole time. So the first failure logs, and
+ * the rest do not (a Redis outage would otherwise write a line every 30s
+ * forever).
+ */
+export function startHeartbeat() {
+    if (timer !== null)
+        return;
+    const tick = () => {
+        beat().catch((err) => {
+            if (warned)
+                return;
+            warned = true;
+            log(`heartbeat failed, so the process dashboard will read this connector as DOWN `
+                + `even while it serves traffic: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    tick(); // the dashboard should not wait 30s for the first one
+    timer = setInterval(tick, INTERVAL_MS);
+    /* Unreferenced so it can never be the reason the process stays alive — the
+       HTTP server is what holds it open, and a lingering interval would keep a
+       shutting-down process from exiting. */
+    timer.unref();
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/http.d.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * The REMOTE entry point — the same nine tools over Streamable HTTP.
+ *
+ * Why this file exists at all: a web client cannot run a process on the user's
+ * machine, so claude.ai and ChatGPT can never reach the stdio package however
+ * well it works. They speak to a URL or to nothing. This is that URL.
+ *
+ *   node dist/http.js        → listens on VIDOFY_MCP_PORT, path /mcp-app
+ *   node dist/index.js       → the stdio server, unchanged
+ *
+ * In production nginx terminates TLS on vidofy.ai and proxies /mcp-app here;
+ * this process never sees the internet directly and never holds a certificate.
+ *
+ * IT IS OAUTH NOW — and the two paragraphs that used to stand here said the
+ * opposite
+ * ------------------------------------------------------------------------
+ * They described a staging step ("it is not OAuth… a fixed bearer header… NOT
+ * the shipping shape") and were true for about a day. They are left mentioned
+ * rather than silently deleted because the thing they got wrong is worth
+ * knowing: the staged shape is now **impossible**, not merely superseded. A
+ * hand-made `vmt_` from the tokens page declares NO resource, this
+ * endpoint always declares a resource (see MCP_PATH below), and the server
+ * refuses that pairing outright. So "No sign-in
+ * + Request headers" cannot work here any more, and a reader who trusted those
+ * paragraphs would spend an afternoon finding out.
+ *
+ * What is built: authorization (`/mcp-app/authorize`), the consent hand-off to
+ * PHP, the code exchange (`/mcp-app/token`), Client ID Metadata Documents, PKCE
+ * S256, and RFC 8707 audience binding. What is NOT built: token revocation over
+ * the protocol — revocation lives on the website's own tokens page, which is why
+ * `revocation_endpoint` is absent from the metadata below rather than advertised
+ * and unrouted.
+ *
+ * STATELESS ON PURPOSE
+ * --------------------
+ * sessionIdGenerator is undefined, so every request stands alone. That is a
+ * measured fit rather than a simplification: this server never pushes a
+ * notification (zero sendNotification calls in the package), because the card
+ * polls get_status through the host instead. Sessions exist to carry
+ * server-initiated messages; with none to carry, holding per-session state would
+ * be a memory leak with a session id on it.
+ */
+export {};