vyra-mcp 0.3.0 → 0.5.0

package/README.md

@@ -6,15 +6,23 @@ performance-based creator campaigns in plain English.
 ## Quick start
 
 1. Create an API key in Vyra: **Settings → Developers → Create key**.
-2. Connect it:
+2. Connect it — one command auto-configures every MCP client you have installed
+   (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code):
 
    ```bash
    npx vyra-mcp connect vyra_sk_your_key_here
    ```
 
-3. Restart Claude Desktop, then ask: _"List my Vyra campaigns"_ or
+3. Restart the client, then ask: _"List my Vyra campaigns"_ or
    _"Create a TikTok campaign with a $5 fee and a $500 budget, then activate it."_
 
+### Options (rarely needed)
+
+```bash
+npx vyra-mcp connect <key> --client cursor   # only one client
+npx vyra-mcp connect <key> --print           # just print a snippet (e.g. ChatGPT Desktop)
+```
+
 ## Tools
 
 On connect, the server tells your agent how Vyra works (performance-based creator

package/dist/api.js

@@ -55,6 +55,12 @@ export async function apiRequest(method, path, body) {
         }
     }
     if (!res.ok) {
+        // A 401 here means a key was sent but rejected — point the user at the fix
+        // instead of surfacing the bare "Invalid or missing API key" envelope.
+        if (res.status === 401) {
+            throw new Error("Vyra rejected the API key (HTTP 401). Generate a fresh key in " +
+                "Settings → Developers and re-run `npx vyra-mcp connect <your-key>`.");
+        }
         const message = json?.error ??
             `HTTP ${res.status} from Vyra`;
         throw new Error(message);

package/dist/cli.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 // Entry point for the `vyra-mcp` binary.
 //
-//   vyra-mcp connect <vyra_sk_…> [--base-url <url>]   wire into Claude Desktop
+//   vyra-mcp connect <vyra_sk_…> [--client <id|all>] [--base-url <url>] [--print]
 //   vyra-mcp serve                                     run the MCP server (stdio)
 //   vyra-mcp                                           same as `serve`
 //
+// connect targets Claude Desktop by default. --client picks another client
+// (claude-code, cursor, windsurf, vscode), `all` configures every detected one,
+// and --print shows a snippet for manual setup (e.g. ChatGPT Desktop).
+//
 // `serve` is the default so MCP clients can spawn the bare binary.
 import { connect } from "./connect.js";
 import { serve } from "./server.js";
@@ -18,11 +22,15 @@ async function main() {
         case "connect": {
             const key = rest.find((a) => !a.startsWith("--"));
             if (!key) {
-                console.error("Usage: npx vyra-mcp connect <your-api-key>");
+                console.error("Usage: npx vyra-mcp connect <your-api-key> [--client <id|all>] [--print]");
                 process.exitCode = 1;
                 return;
             }
-            connect(key, getFlag(rest, "--base-url"));
+            connect(key, {
+                client: getFlag(rest, "--client"),
+                baseUrl: getFlag(rest, "--base-url"),
+                print: rest.includes("--print") || rest.includes("--manual"),
+            });
             return;
         }
         case undefined:

package/dist/clients.js

@@ -0,0 +1,122 @@
+// Registry of MCP clients we can auto-configure, plus the logic to merge our
+// "vyra" server into each one's config file.
+//
+// Most clients share the `{ mcpServers: { vyra: { command, args, env } } }`
+// shape. VS Code is the odd one out (`servers`, with an explicit `type`).
+// ChatGPT Desktop has no stable local-stdio config file — users add it through
+// its connector UI — so it's covered by the printed manual snippet instead.
+import { homedir, platform } from "node:os";
+import { join, dirname } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+// Claude Desktop config path, per OS.
+function claudeDesktopPath() {
+    const home = homedir();
+    switch (platform()) {
+        case "darwin":
+            return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+        case "win32":
+            return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+        default:
+            return join(home, ".config", "Claude", "claude_desktop_config.json");
+    }
+}
+export const CLIENTS = [
+    {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        format: "mcpServers",
+        resolvePath: claudeDesktopPath,
+    },
+    {
+        id: "claude-code",
+        label: "Claude Code (CLI)",
+        format: "mcpServers",
+        resolvePath: () => join(homedir(), ".claude.json"), // user scope
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        format: "mcpServers",
+        resolvePath: () => join(homedir(), ".cursor", "mcp.json"),
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf",
+        format: "mcpServers",
+        resolvePath: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+    },
+    {
+        id: "vscode",
+        label: "VS Code (Copilot)",
+        format: "vscode",
+        resolvePath: () => join(process.cwd(), ".vscode", "mcp.json"),
+    },
+];
+export function getClient(id) {
+    return CLIENTS.find((c) => c.id === id);
+}
+// The server entry we inject. `npx -y` runs it with no global install. VS Code
+// needs an explicit "stdio" type field; everyone else doesn't.
+export function serverEntry(apiKey, baseUrl, vscode = false) {
+    const env = { VYRA_API_KEY: apiKey };
+    if (baseUrl)
+        env.VYRA_BASE_URL = baseUrl;
+    const base = { command: "npx", args: ["-y", "vyra-mcp", "serve"], env };
+    return vscode ? { type: "stdio", ...base } : base;
+}
+// Merge our server into a client's config, preserving everything else. Returns
+// a result rather than throwing so the caller can report per-client outcomes.
+export function writeClientConfig(client, apiKey, baseUrl) {
+    const path = client.resolvePath();
+    // Read existing config (treat missing/empty as {}). Never clobber a file we
+    // can't parse — report it and let the caller fall back to the manual snippet.
+    let config = {};
+    if (existsSync(path)) {
+        try {
+            const raw = readFileSync(path, "utf8");
+            if (raw.trim()) {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object") {
+                    config = parsed;
+                }
+            }
+        }
+        catch {
+            return { ok: false, path, error: "existing config isn't valid JSON" };
+        }
+    }
+    const key = client.format === "vscode" ? "servers" : "mcpServers";
+    const entry = serverEntry(apiKey, baseUrl, client.format === "vscode");
+    const existing = config[key] && typeof config[key] === "object"
+        ? config[key]
+        : {};
+    // Immutable merge: keep every other server, add/replace ours.
+    const next = { ...config, [key]: { ...existing, vyra: entry } };
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf8");
+        return { ok: true, path };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : "write failed";
+        return { ok: false, path, error: reason };
+    }
+}
+// Is this client plausibly installed? Used by auto-detect so we don't scatter
+// config files for apps the user doesn't have. A client counts as present if
+// its config file exists, or its parent dir exists AND that parent is
+// client-specific (not the home dir or cwd — those exist everywhere, e.g.
+// Claude Code's ~/.claude.json or VS Code's ./.vscode).
+export function isClientDetected(client) {
+    const path = client.resolvePath();
+    if (existsSync(path))
+        return true;
+    const dir = dirname(path);
+    if (dir === homedir() || dir === process.cwd())
+        return false;
+    return existsSync(dir);
+}
+// Copy-paste config for any client we don't write automatically (e.g. ChatGPT).
+export function manualSnippet(apiKey, baseUrl) {
+    return JSON.stringify({ mcpServers: { vyra: serverEntry(apiKey, baseUrl) } }, null, 2);
+}

package/dist/connect.js

@@ -1,98 +1,68 @@
-// `vyra-mcp connect <key>` — one-command setup. Adds (or updates) a "vyra" entry
-// in the Claude Desktop config so Claude launches this server with the brand's
-// API key. Other MCP clients can copy the same snippet manually.
-import { homedir, platform } from "node:os";
-import { join } from "node:path";
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
-// Where Claude Desktop keeps its config, per OS.
-function claudeConfigPath() {
-    const home = homedir();
-    switch (platform()) {
-        case "darwin":
-            return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-        case "win32":
-            return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
-        default:
-            // Linux / others
-            return join(home, ".config", "Claude", "claude_desktop_config.json");
+// `vyra-mcp connect <key> [--client <id|all>] [--base-url <url>] [--print]`
+//
+// Wires the Vyra MCP server into one or more MCP clients. Default target is
+// Claude Desktop. Use --client to pick another (claude-code, cursor, windsurf,
+// vscode), --client all to configure every detected client, or --print to just
+// show the config snippet for manual setup (e.g. ChatGPT Desktop).
+import { CLIENTS, getClient, writeClientConfig, isClientDetected, manualSnippet, } from "./clients.js";
+// Decide which clients to write to. With no --client flag we auto-detect and
+// configure EVERY installed client, so the common case is just one command:
+//   npx vyra-mcp connect <key>
+function resolveTargets(client) {
+    if (!client || client === "all") {
+        // Only touch clients that look installed, so we don't scatter stray files.
+        return CLIENTS.filter(isClientDetected);
     }
-}
-// Read the existing config if present; return {} on missing/corrupt so we never
-// wipe a user's setup because of a parse error.
-function readConfig(path) {
-    if (!existsSync(path))
-        return {};
-    try {
-        const raw = readFileSync(path, "utf8");
-        if (!raw.trim())
-            return {};
-        const parsed = JSON.parse(raw);
-        return typeof parsed === "object" && parsed !== null
-            ? parsed
-            : {};
-    }
-    catch {
-        console.warn("⚠️  Existing Claude config wasn't valid JSON — leaving it untouched and printing manual steps instead.");
-        throw new Error("UNREADABLE_CONFIG");
+    const def = getClient(client);
+    if (!def) {
+        const ids = CLIENTS.map((c) => c.id).join(", ");
+        return `Unknown client "${client}". Supported: ${ids}, all.`;
     }
+    return [def];
 }
-// The server entry we inject. `npx -y` lets Claude run it with no global install.
-function vyraEntry(apiKey, baseUrl) {
-    const env = { VYRA_API_KEY: apiKey };
-    if (baseUrl)
-        env.VYRA_BASE_URL = baseUrl;
-    return {
-        command: "npx",
-        args: ["-y", "vyra-mcp", "serve"],
-        env,
-    };
-}
-// Print a copy-paste snippet for clients we can't auto-configure.
-function printManual(apiKey, baseUrl) {
-    const snippet = {
-        mcpServers: { vyra: vyraEntry(apiKey, baseUrl) },
-    };
-    console.log("\nAdd this to your MCP client config manually:\n");
-    console.log(JSON.stringify(snippet, null, 2));
-    console.log("");
-}
-export function connect(apiKey, baseUrl) {
+export function connect(apiKey, opts = {}) {
     const trimmed = apiKey.trim();
     if (!trimmed || !trimmed.startsWith("vyra_sk_")) {
         console.error("That doesn't look like a Vyra key. Create one in Settings → Developers (it starts with vyra_sk_).");
         process.exitCode = 1;
         return;
     }
-    const path = claudeConfigPath();
-    let config;
-    try {
-        config = readConfig(path);
-    }
-    catch {
-        // Corrupt existing config — don't touch it, just show manual steps.
-        printManual(trimmed, baseUrl);
+    // Manual mode — just print the snippet for hand-configuring any client.
+    if (opts.print) {
+        console.log("\nAdd this to your MCP client config:\n");
+        console.log(manualSnippet(trimmed, opts.baseUrl));
+        console.log("");
         return;
     }
-    // Immutable merge: keep every existing server, add/replace ours.
-    const next = {
-        ...config,
-        mcpServers: {
-            ...(config.mcpServers ?? {}),
-            vyra: vyraEntry(trimmed, baseUrl),
-        },
-    };
-    try {
-        mkdirSync(join(path, ".."), { recursive: true });
-        writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf8");
-    }
-    catch (err) {
-        const reason = err instanceof Error ? err.message : "write failed";
-        console.error(`Couldn't write ${path}: ${reason}`);
-        printManual(trimmed, baseUrl);
+    const targets = resolveTargets(opts.client);
+    if (typeof targets === "string") {
+        console.error(targets);
         process.exitCode = 1;
         return;
     }
-    console.log("✓ Vyra connected to Claude Desktop.");
-    console.log(`  Config: ${path}`);
-    console.log("  Restart Claude Desktop, then ask it to list your campaigns.");
+    if (targets.length === 0) {
+        // Nothing auto-detected — just hand them the snippet to paste, rather than
+        // making them run another command.
+        console.log("No MCP client auto-detected. Paste this into your client's MCP config:\n");
+        console.log(manualSnippet(trimmed, opts.baseUrl));
+        console.log("");
+        return;
+    }
+    let anyOk = false;
+    for (const client of targets) {
+        const res = writeClientConfig(client, trimmed, opts.baseUrl);
+        if (res.ok) {
+            anyOk = true;
+            console.log(`✓ ${client.label} — ${res.path}`);
+        }
+        else {
+            console.log(`• ${client.label} — skipped (${res.error})`);
+        }
+    }
+    if (anyOk) {
+        console.log("\nRestart the client, then ask it to list your Vyra campaigns.");
+    }
+    else {
+        console.log("\nNothing was written. Use --print for a manual snippet.");
+    }
 }

package/dist/server.js

@@ -38,8 +38,92 @@ async function run(fn) {
         return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
     }
 }
+// Campaign draft fields, shared by create_campaign and update_campaign so the
+// two never drift. Money fields are integer cents.
+const CAMPAIGN_FIELDS = {
+    name: z.string().describe("Campaign name"),
+    fixed_fee_cents: z
+        .number()
+        .int()
+        .describe("Guaranteed fee paid to each creator on approval, in cents"),
+    budget_cents: z.number().int().describe("Total campaign budget in cents"),
+    objective: z.string().optional().describe("Short objective/goal"),
+    platform: z
+        .enum(["tiktok", "instagram", "youtube"])
+        .optional()
+        .describe("Target platform (default tiktok)"),
+    countries: z
+        .array(z.string())
+        .optional()
+        .describe("Allowed 2-letter country codes"),
+    bonus_cap_cents: z
+        .number()
+        .int()
+        .optional()
+        .describe("Max performance bonus per creator, in cents"),
+    bonus_type: z.enum(["milestone", "cpm", "none"]).optional(),
+    bonus_cpm_cents: z
+        .number()
+        .int()
+        .optional()
+        .describe("Bonus per 1000 views, in cents (when bonus_type is cpm)"),
+    languages: z
+        .array(z.string())
+        .optional()
+        .describe("Allowed creator languages"),
+    min_followers: z.number().int().optional(),
+    max_followers: z.number().int().optional(),
+    min_quality_score: z
+        .number()
+        .int()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe("Minimum AI quality score (0–100) a submission must hit"),
+    require_connected_account: z
+        .boolean()
+        .optional()
+        .describe("Require creators to have a connected social account"),
+    watch_window_days: z
+        .number()
+        .int()
+        .optional()
+        .describe("Days to track views before the bonus settles"),
+    submission_deadline_hours: z
+        .number()
+        .int()
+        .optional()
+        .describe("Hours a creator has to post after joining"),
+    min_video_seconds: z
+        .number()
+        .int()
+        .optional()
+        .describe("Minimum video length, in seconds"),
+    max_video_seconds: z
+        .number()
+        .int()
+        .optional()
+        .describe("Maximum video length, in seconds"),
+    key_message: z
+        .string()
+        .optional()
+        .describe("The brief / what creators should communicate"),
+    hashtags: z.array(z.string()).optional(),
+    promo_link: z
+        .string()
+        .optional()
+        .describe("A link OR a plain discount code (e.g. SAVE20)"),
+    assets: z
+        .array(z.object({
+        kind: z.enum(["logo", "video", "screenshot"]),
+        url: z.string().describe("Hosted URL of the asset"),
+        file_name: z.string().optional(),
+    }))
+        .optional()
+        .describe("Brand assets to attach, by URL (logo/demo video/screenshots)"),
+};
 export function buildServer() {
-    const server = new McpServer({ name: "vyra", version: "0.3.0" }, { instructions: INSTRUCTIONS });
+    const server = new McpServer({ name: "vyra", version: "0.5.0" }, { instructions: INSTRUCTIONS });
     // --- Orientation --------------------------------------------------------
     // One call an agent makes first to ground itself: live state + how Vyra works
     // + exactly what a campaign needs. Stops it from asking irrelevant questions.
@@ -88,6 +172,17 @@ export function buildServer() {
         description: "Get the brand's available prepaid balance (in cents and USD). Use before activating a campaign to confirm funds.",
         inputSchema: {},
     }, () => run(() => apiRequest("GET", "/wallet")));
+    server.registerTool("create_topup_link", {
+        title: "Add credits (Stripe checkout link)",
+        description: "Start a Stripe Checkout to add credits to the wallet and return the hosted URL. Card payment happens in the browser (a card can't be charged headlessly), so give the user the link to open once — the balance updates automatically after payment. 1 credit = $1. Use this when activate_campaign reports insufficient funds.",
+        inputSchema: {
+            credits: z
+                .number()
+                .int()
+                .min(1)
+                .describe("Credits to add (1 credit = $1)"),
+        },
+    }, ({ credits }) => run(() => apiRequest("POST", "/wallet/topup", { credits })));
     // --- Campaigns: read ----------------------------------------------------
     server.registerTool("list_campaigns", {
         title: "List campaigns",
@@ -136,58 +231,13 @@ export function buildServer() {
     server.registerTool("create_campaign", {
         title: "Create campaign (draft)",
         description: "Create a new draft campaign. It is NOT live yet — call activate_campaign after funding. All money fields are integer cents.",
-        inputSchema: {
-            name: z.string().describe("Campaign name"),
-            fixed_fee_cents: z
-                .number()
-                .int()
-                .describe("Guaranteed fee paid to each creator on approval, in cents"),
-            budget_cents: z
-                .number()
-                .int()
-                .describe("Total campaign budget in cents"),
-            objective: z.string().optional().describe("Short objective/goal"),
-            platform: z
-                .enum(["tiktok", "instagram", "youtube"])
-                .optional()
-                .describe("Target platform (default tiktok)"),
-            countries: z
-                .array(z.string())
-                .optional()
-                .describe("Allowed 2-letter country codes"),
-            bonus_cap_cents: z
-                .number()
-                .int()
-                .optional()
-                .describe("Max performance bonus per creator, in cents"),
-            bonus_type: z.enum(["milestone", "cpm", "none"]).optional(),
-            bonus_cpm_cents: z
-                .number()
-                .int()
-                .optional()
-                .describe("Bonus per 1000 views, in cents (when bonus_type is cpm)"),
-            min_followers: z.number().int().optional(),
-            watch_window_days: z
-                .number()
-                .int()
-                .optional()
-                .describe("Days to track views before the bonus settles"),
-            key_message: z
-                .string()
-                .optional()
-                .describe("The brief / what creators should communicate"),
-            hashtags: z.array(z.string()).optional(),
-            promo_link: z.string().optional(),
-            assets: z
-                .array(z.object({
-                kind: z.enum(["logo", "video", "screenshot"]),
-                url: z.string().describe("Hosted URL of the asset"),
-                file_name: z.string().optional(),
-            }))
-                .optional()
-                .describe("Brand assets to attach, by URL (logo/demo video/screenshots)"),
-        },
+        inputSchema: CAMPAIGN_FIELDS,
     }, (args) => run(() => apiRequest("POST", "/campaigns", args)));
+    server.registerTool("update_campaign", {
+        title: "Update campaign (draft only)",
+        description: "Edit a DRAFT campaign's fields (only drafts can be edited — a live campaign can't be changed). Pass the full set of fields the draft should have; money fields are integer cents.",
+        inputSchema: { campaign_id: z.string().describe("The campaign id"), ...CAMPAIGN_FIELDS },
+    }, ({ campaign_id, ...fields }) => run(() => apiRequest("PATCH", `/campaigns/${campaign_id}`, fields)));
     server.registerTool("list_campaign_assets", {
         title: "List campaign assets",
         description: "List the brand assets (logo, demo video, screenshots) attached to a campaign.",
@@ -223,6 +273,20 @@ export function buildServer() {
             campaign_id: z.string().describe("The campaign id to pause"),
         },
     }, ({ campaign_id }) => run(() => apiRequest("POST", `/campaigns/${campaign_id}/pause`)));
+    server.registerTool("cancel_campaign", {
+        title: "Cancel campaign",
+        description: "Close a campaign. Releases the reserved budget for unfilled slots back to the wallet and refunds join fees to creators who joined but won't earn. Cannot be undone.",
+        inputSchema: {
+            campaign_id: z.string().describe("The campaign id to cancel"),
+        },
+    }, ({ campaign_id }) => run(() => apiRequest("POST", `/campaigns/${campaign_id}/cancel`)));
+    server.registerTool("get_campaign_report", {
+        title: "Get campaign report",
+        description: "Performance report for a campaign: creators joined, videos live, approval rate, verified views, engagement, the views trend, and a per-submission breakdown.",
+        inputSchema: {
+            campaign_id: z.string().describe("The campaign id"),
+        },
+    }, ({ campaign_id }) => run(() => apiRequest("GET", `/campaigns/${campaign_id}/report`)));
     return server;
 }
 // Start the server on stdio (how MCP clients spawn it as a child process).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vyra-mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Drive Vyra from Claude, ChatGPT, or any MCP client — manage performance-based creator campaigns in plain English.",
   "license": "MIT",
   "type": "module",