@vidofy/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vidofy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# @vidofy/mcp
+
+[![npm](https://img.shields.io/npm/v/@vidofy/mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/@vidofy/mcp)
+[![node](https://img.shields.io/badge/node-%E2%89%A518-5fa04e?logo=node.js&logoColor=white)](https://nodejs.org)
+[![licence](https://img.shields.io/badge/licence-MIT-blue)](./LICENSE)
+[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-6f42c1)](https://modelcontextprotocol.io)
+
+**MCP server for [Vidofy](https://vidofy.ai)** — generate images, video, audio and speech from
+Claude Desktop, Cursor, or any MCP client, **billed to your own Vidofy account**, at the same
+prices the website charges.
+
+Over 570 models, including **Veo 3.1**, **Kling 3.0**, **Flux 2**, **Seedance 2.5**, **Wan 2.7**,
+**Hailuo 2.3**, **Runway**, **Luma Ray 2**, **Qwen Image 3.0**, **Vidu Q3** and **LTX 2** —
+text-to-video, image-to-video, text-to-image, image editing, video and photo effects, lipsync,
+text-to-speech and voice cloning. The agent browses the catalogue, prices a generation before
+running it, and follows one to its result.
+
+> **Status: v0.1.0, the first public release.**
+>
+> **This server is for personal Vidofy accounts.** It takes one credential,
+> `VIDOFY_TOKEN`, and spends **your own coins** — the same balance the website
+> spends, at the same prices. There is no other billing mode: `VIDOFY_API_KEY` is
+> refused at startup, and that is a decision, not a feature waiting on a release.
+
+## Tools
+
+| Tool | What it does | Spends |
+|---|---|---|
+| `list_modes` | What Vidofy can generate: text-to-image, image-to-video, lipsync, speech… | no |
+| `list_models` | The models in one mode, with each one's credit cost and rough duration | no |
+| `get_model` | One model's full input contract: a JSON Schema, its file slots and their limits | no |
+| `estimate_cost` | What a generation will cost, before running it | no |
+| **`generate`** | **Runs it. The only tool that spends the balance.** | **yes** |
+| `get_status` | Whether a generation has finished | no |
+| `get_result` | The finished media | no |
+| `get_balance` | Coins left, and how many expire with the subscription | no |
+| `get_usage` | Recent generations and what they cost | no |
+
+The usual order is `list_modes` → `list_models` → `get_model` → `estimate_cost` → `generate`
+→ `get_status` → `get_result`.
+
+`generate` is the only tool without `readOnlyHint`, which is what tells a client to ask the user
+before running it. It charges at **submit**, not on success, and returns immediately with an id —
+a generation takes from ~30 seconds to several minutes, so the agent polls `get_status` rather
+than holding the call open. Output is **private by default**; pass `public: true` only when the
+user asked for a permanent public link.
+
+File inputs take a **path on the machine running the server**. The package reads the user's own
+file and streams it with the submit — it never makes a temporary copy — and checks the extension
+and size against that model's own limits first, so a file the server would reject never leaves
+the disk.
+
+**Not exposed, deliberately:** checkout, auto top-up, purchases, referrals, the daily reward.
+Nothing in this package can buy coins or change a plan, however it is prompted.
+
+## Setup
+
+There are two ways in. **Take the first one** unless your client cannot do it.
+
+### 1. Remote connector — nothing to install
+
+Give your client this URL:
+
+```
+https://vidofy.ai/mcp-app
+```
+
+You sign in **in your browser** and approve once. No token to copy, nothing to keep in a
+config file, and nothing to update when this package changes.
+
+| Client | How |
+|---|---|
+| **Claude.ai** · **Claude Desktop** | Settings → Connectors → *Add custom connector* → paste the URL → **Connect**, then approve the sign-in. They share one list: add it in either and it appears in both. Available on every plan, including Free — where you get one connector. |
+| **ChatGPT** | Settings → Connectors → add a custom connector (no such option? turn on Developer Mode in Settings first) → paste the URL → **Connect**, then approve. On a Business or Enterprise workspace an administrator adds it for everyone. |
+| **Claude Code** · **Codex** · **Cursor** | Each accepts a remote MCP server URL. Follow that client's own MCP documentation and give it the URL above. |
+
+Then ask it: *"list Vidofy modes"* to confirm the connection, and
+*"make me a 5-second clip of a red bicycle"* — it prices the generation before running it.
+
+### 2. Local stdio server — for a client that only speaks stdio
+
+Create a personal MCP token at **vidofy.ai → Studio → Account → MCP Access**. It is shown once.
+
+```jsonc
+// claude_desktop_config.json   (Cursor: .cursor/mcp.json — same shape)
+{
+  "mcpServers": {
+    "vidofy": {
+      "command": "npx",
+      "args": ["-y", "@vidofy/mcp"],
+      "env": { "VIDOFY_TOKEN": "vmt_..." }
+    }
+  }
+}
+```
+
+`npx` fetches it on first run. Prefer a pinned copy? `npm i -g @vidofy/mcp`, then:
+
+```jsonc
+{ "command": "vidofy-mcp", "env": { "VIDOFY_TOKEN": "vmt_..." } }
+```
+
+Both paths reach the same account, the same models and the same balance. The difference is
+only where the process runs and how you prove who you are.
+
+### Environment
+
+| Variable | Required | What it does |
+|---|---|---|
+| `VIDOFY_TOKEN` | **yes** | Personal MCP token (`vmt_…`). Spends **your own Vidofy coins**, exactly as the studio does. |
+| `VIDOFY_API_BASE` | no | Override the origin the server talks to — an **origin only**, no path. Defaults to `https://vidofy.ai`, which is what you want. |
+
+`VIDOFY_API_KEY` is recognised only in order to be **refused**: a `vky_…` key bills a
+different balance, which this server does not serve. Setting it stops startup with a message
+naming the token to use instead — and setting *both* is refused too, since the two bill
+different balances and no precedence rule is worth having to remember.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run inspect      # MCP Inspector — spends nothing
+```
+
+`VIDOFY_API_BASE` points it at a different origin, if you are running one.
+
+**Nothing here writes to stdout.** With stdio transport, stdout *is* the protocol channel — a
+single stray `console.log()` puts a non-JSON line in the stream and the client drops the
+connection with an error that explains nothing. Diagnostics go to stderr via the `log()` helper
+in `src/index.ts`.
+
+## Layout
+
+```
+src/config.ts          credential + mode + base URL, validated at startup
+src/backend.ts         the only place that talks HTTP: auth, retries, multipart, errors
+src/schema.ts          one model's m_options → a JSON Schema the agent can fill in
+src/map/b2c.ts         both response shapes → one; strips the provider cost
+src/tools/info.ts      list_modes, list_models, get_model
+src/tools/generation.ts estimate_cost, generate, get_status, get_result
+src/tools/account.ts   get_balance, get_usage
+src/index.ts           the server: stdio transport, tool registration, annotations
+
+
+server.json     MCP registry manifest (name must match package.json "mcpName")
+```
+
+## Licence
+
+MIT

package/dist/backend.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The one place that talks to Vidofy over HTTP.
+ *
+ * Everything else in this package builds a request description and hands it
+ * here, so door selection, authentication, retries, timeouts and error shape
+ * are decided once instead of in nine tools.
+ *
+ * WHAT THIS FILE IS RESPONSIBLE FOR
+ *   · picking /app/v1 or /api/v1 from the configured mode
+ *   · attaching the credential and the User-Agent on every call
+ *   · multipart bodies — one form field per m_* key, exactly as the studio posts
+ *   · carrying an Idempotency-Key when the caller supplies one
+ *   · retrying the things that are worth retrying, and nothing else
+ *   · turning both transport failures and API error envelopes into one error type
+ */
+import { type Config } from './config.js';
+/**
+ * Anything that went wrong, from either side of the wire.
+ *
+ * `code` is the machine-readable one — the API's own `error` field where there
+ * was a response, or a transport pseudo-code where there was not. `message` is
+ * what a person (or a model) should read.
+ */
+export declare class VidofyError extends Error {
+    readonly code: string;
+    readonly httpStatus: number | null;
+    /** Extra fields the API returned, e.g. `allowed` on INVALID_MODE. */
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, httpStatus?: number | null, 
+    /** Extra fields the API returned, e.g. `allowed` on INVALID_MODE. */
+    details?: Record<string, unknown>);
+}
+/** Exported for get_status, which holds its call open rather than letting the
+ *  agent poll in a tight loop — one definition, not a second one that drifts. */
+export declare const sleep: (ms: number) => Promise<void>;
+/** A local file to attach to a multipart request. */
+export interface FileField {
+    /** The form field name — m_image, m_first_frame, m_multi_image_file_0, … */
+    field: string;
+    /** Absolute or relative path on the machine running this server. */
+    path: string;
+    /**
+     * Extensions this slot accepts, with or without the dot. Comes from the
+     * model's own m_upload_*_settings via get_model, already defaulted the way
+     * the server defaults them. REQUIRED in practice: an empty or missing list
+     * is refused, not waved through — see the check in buildBody.
+     */
+    accept?: readonly string[];
+    /** The slot's max_size in megabytes, from the same place. */
+    maxSizeMb?: number;
+    /**
+     * The slot's max_duration in seconds, from the same place. 0/absent = no
+     * cap. Enforced only when the file's own header states its length exactly
+     * — see media-duration.ts for which formats those are, and why a guess is
+     * not allowed to refuse an upload.
+     */
+    maxDurationSec?: number;
+}
+export interface RequestOptions {
+    method: 'GET' | 'POST';
+    /** Path AFTER the version prefix, e.g. 'info/modes'. No leading slash. */
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    /**
+     * Form fields. Sent as multipart when `files` is present, otherwise as
+     * application/x-www-form-urlencoded — the two shapes the submit handler
+     * reads. JSON is deliberately NOT used on the account door: measured in
+     * early testing, a JSON body from a session caller is not decoded at all by
+     * the submit handler, so it would silently lose every field.
+     */
+    form?: Record<string, string | number | boolean | undefined>;
+    files?: FileField[];
+    /**
+     * Same value across every retry of one logical call — that is what makes
+     * retrying a POST safe rather than a way to pay twice. Generated once by
+     * the caller, never here.
+     */
+    idempotencyKey?: string;
+    timeoutMs?: number;
+    /**
+     * Return the body instead of throwing when a 200 carries `success: false`.
+     *
+     * For the two endpoints that report on a JOB: a generation that failed is
+     * a successful call whose answer happens to be bad news, and the caller's
+     * mapper is what turns it into `{done:true, status:'failed'}`. Everywhere
+     * else an envelope error is still an error.
+     */
+    allowEnvelopeError?: boolean;
+    /**
+     * Cap the attempts for this call. Defaults to MAX_ATTEMPTS.
+     *
+     * `generate` sets 1. Retrying it is safe on the SERVER — the
+     * Idempotency-Key dedupes — but the whole budget still has to finish
+     * inside the client's 60s tool-call timeout, or the client gives up while
+     * the charge lands and the agent retries with a new key. One attempt, well
+     * inside the window, beats four that outlive the caller.
+     */
+    maxAttempts?: number;
+}
+/** A fresh idempotency key. Callers make ONE per logical operation. */
+export declare function newIdempotencyKey(): string;
+/**
+ * An idempotency key derived from WHAT IS BEING ASKED FOR, inside a window.
+ *
+ * The server dedupes on (user, origin, m_client_request_id) and this package
+ * sent a randomUUID() per invocation, so that tuple could never repeat and
+ * the dedupe could never fire: two identical generate calls were two
+ * generations and two charges. The mechanism existed on both sides and was
+ * joined by a value guaranteed to differ.
+ *
+ * NO TIME COMPONENT IN THE KEY, deliberately — that was tried and is wrong.
+ * The expiry a derived key needs (the same prompt next week must generate
+ * again, not replay) is a property of the LOOKUP, and it now lives there:
+ * The server's idempotent-lookup takes a max age and the submit
+ * handler passes 60 seconds for an MCP caller. Hashing a time bucket into the
+ * key instead makes a tumbling grid, so two calls seconds apart miss each
+ * other whenever a boundary falls between them — measured on the first live
+ * pair tried: 11 seconds apart, two jobs, two charges. A bound on the query
+ * is a real "within 60s of each other" at any alignment.
+ *
+ * Files are identified by path AND by size+mtime, so editing an image and
+ * re-running inside the window is a different request rather than a cached
+ * answer. A path that cannot be stat'd contributes its raw path and the real
+ * complaint arrives later, from the code whose job that is.
+ */
+export declare function contentIdempotencyKey(parts: Record<string, unknown>, filePaths?: readonly string[]): string;
+/**
+ * Perform one request, with retries.
+ *
+ * Returns the parsed JSON body on success. Throws VidofyError on anything else,
+ * including a 200 whose envelope says `success: false`.
+ */
+export declare function request<T = unknown>(cfg: Config, opts: RequestOptions): Promise<T>;