vyra-mcp 0.2.0 → 0.4.0

package/README.md

@@ -6,24 +6,37 @@ 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
+marketing, **not** paid ads) so it won't ask irrelevant ad-platform questions.
+
 | Tool | What it does |
 |------|--------------|
+| `get_started` | Call first — how Vyra works + live wallet/campaigns + required fields |
 | `get_wallet_balance` | Available prepaid balance |
 | `list_campaigns` | All your campaigns |
 | `get_campaign` | One campaign by id |
 | `list_campaign_slots` | Creators who joined, with status + views |
 | `get_submission` | One submission's metrics, cost, watch-window |
+| `estimate_campaign` | Preview how many creators a budget funds (no spend) |
 | `create_campaign` | Create a draft campaign (optionally with assets) |
 | `activate_campaign` | Fund-check, reserve budget, go live |
 | `pause_campaign` | Stop new creators from joining |

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

@@ -7,6 +7,25 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { apiRequest } from "./api.js";
+// Injected into the agent's context the moment it connects. This is what stops
+// agents from asking generic ad-platform questions (daily budget, destination
+// URL, ad placements) — Vyra is not paid ads.
+const INSTRUCTIONS = `Vyra is a PERFORMANCE-BASED CREATOR MARKETING platform — NOT a paid-ads tool (not Meta/Google/TikTok Ads).
+
+How it works: a brand funds prepaid credits, then creates a campaign that pays small creators to post short organic videos to their OWN audiences. Each creator earns a FIXED FEE when their video is approved, plus an optional PERFORMANCE BONUS based on views over a watch window. The brand buys "slots" — one creator per slot.
+
+So DO NOT ask about: daily ad budget, destination/landing URL as an ad target, ad placements, bid strategy, conversion tracking pixels, or audiences-to-target-with-ads. Those don't apply.
+
+Recommended workflow when a user wants to run a campaign:
+1. Call get_started first — it returns the brand's live wallet balance, existing campaigns, and the exact fields a campaign needs. Ground yourself in that before asking anything.
+2. To create a campaign you only NEED: a name, a fixed_fee_cents (guaranteed pay per creator on approval), and a budget_cents (total — budget ÷ per-creator cost = number of creator slots). Everything else has sensible defaults.
+3. Helpful extras: key_message (the brief — what creators should highlight), a bonus (bonus_type "milestone" or "cpm" + bonus_cap_cents), targeting (countries, min/max_followers), content rules (watch_window_days, min/max_video_seconds, submission_deadline_hours), hashtags, promo_link, and assets (logo/demo video/screenshots attached BY URL).
+4. create_campaign makes a DRAFT — it is not live and spends nothing yet.
+5. To go live, call activate_campaign. This RESERVES the budget from the wallet, so the wallet must be funded first (check get_wallet_balance). If funds are too low, tell the user to add credits in the Vyra dashboard.
+
+NEVER INVENT NUMBERS. Do not guess or calculate slot counts, costs, or balances yourself. Always read them from tool results: get_wallet_balance for funds, estimate_campaign to preview how many creators a budget funds, and the value create_campaign returns for the real slot count. If you don't have a number from a tool, call the tool — don't make one up.
+
+IMPORTANT: All money fields are integer CENTS (e.g. $5.00 = 500). Platform fees/margins are internal — never ask about or expose them. Confirm the draft with the user before activating (activation spends real credits).`;
 // Wrap any tool body so a thrown error becomes a clean MCP error result instead
 // of crashing the transport. Success returns the value as pretty JSON text.
 async function run(fn) {
@@ -20,7 +39,49 @@ async function run(fn) {
     }
 }
 export function buildServer() {
-    const server = new McpServer({ name: "vyra", version: "0.2.0" });
+    const server = new McpServer({ name: "vyra", version: "0.3.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.
+    server.registerTool("get_started", {
+        title: "Get started / account overview",
+        description: "Call this FIRST. Returns how Vyra works, the brand's live wallet balance and existing campaigns, and the exact fields needed to create a campaign. Use it to avoid asking the user for anything Vyra doesn't need.",
+        inputSchema: {},
+    }, () => run(async () => {
+        // Pull live state; tolerate either call failing so orientation still works.
+        const [wallet, campaigns] = await Promise.all([
+            apiRequest("GET", "/wallet").catch(() => null),
+            apiRequest("GET", "/campaigns").catch(() => null),
+        ]);
+        return {
+            platform: "Vyra — performance-based creator marketing. Brands pay small creators a fixed fee + performance bonus to post short organic videos. NOT paid ads.",
+            wallet,
+            campaigns,
+            to_create_a_campaign: {
+                required: {
+                    name: "Campaign name",
+                    fixed_fee_cents: "Guaranteed pay per creator on approval (cents)",
+                    budget_cents: "Total budget (cents). budget ÷ per-creator cost = creator slots",
+                },
+                optional: {
+                    key_message: "The brief — what creators should highlight",
+                    bonus: "bonus_type 'milestone'|'cpm' + bonus_cap_cents (and bonus_cpm_cents for cpm)",
+                    targeting: "countries[], min_followers, max_followers",
+                    content_rules: "watch_window_days, min_video_seconds, max_video_seconds, submission_deadline_hours",
+                    hashtags: "hashtags[]",
+                    promo_link: "Link or discount code",
+                    assets: "Attach logo/demo video/screenshots by URL (attach_campaign_asset)",
+                    platform: "tiktok (default) | instagram | youtube",
+                },
+                notes: [
+                    "All money is integer cents ($5 = 500).",
+                    "create_campaign makes a DRAFT (spends nothing).",
+                    "activate_campaign reserves budget from the wallet — fund it first.",
+                    "Do NOT ask about ad budgets, placements, or destination URLs — Vyra is not paid ads.",
+                ],
+            },
+        };
+    }));
     // --- Wallet -------------------------------------------------------------
     server.registerTool("get_wallet_balance", {
         title: "Get wallet balance",
@@ -56,6 +117,22 @@ export function buildServer() {
         },
     }, ({ submission_id }) => run(() => apiRequest("GET", `/submissions/${submission_id}`)));
     // --- Campaigns: write ---------------------------------------------------
+    server.registerTool("estimate_campaign", {
+        title: "Estimate creator slots",
+        description: "Preview how many creator slots a budget funds, WITHOUT creating anything. Call this to show the user real numbers before creating a campaign — never compute slot counts yourself.",
+        inputSchema: {
+            fixed_fee_cents: z
+                .number()
+                .int()
+                .describe("Guaranteed fee per creator, in cents"),
+            budget_cents: z.number().int().describe("Total budget, in cents"),
+            bonus_cap_cents: z
+                .number()
+                .int()
+                .optional()
+                .describe("Max performance bonus per creator, in cents"),
+        },
+    }, (args) => run(() => apiRequest("POST", "/campaigns/estimate", args)));
     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.",

package/package.json

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