vyra-mcp 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# vyra-mcp
+
+Drive [Vyra](https://creator-networks-sigma.vercel.app) from Claude, ChatGPT, or any MCP client — manage
+performance-based creator campaigns in plain English.
+
+## Quick start
+
+1. Create an API key in Vyra: **Settings → Developers → Create key**.
+2. Connect it:
+
+   ```bash
+   npx vyra-mcp connect vyra_sk_your_key_here
+   ```
+
+3. Restart Claude Desktop, then ask: _"List my Vyra campaigns"_ or
+   _"Create a TikTok campaign with a $5 fee and a $500 budget, then activate it."_
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `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 |
+| `create_campaign` | Create a draft campaign |
+| `activate_campaign` | Fund-check, reserve budget, go live |
+| `pause_campaign` | Stop new creators from joining |
+
+## Manual config
+
+`connect` writes a `vyra` entry into your Claude Desktop config. To wire another
+client by hand:
+
+```json
+{
+  "mcpServers": {
+    "vyra": {
+      "command": "npx",
+      "args": ["-y", "vyra-mcp", "serve"],
+      "env": { "VYRA_API_KEY": "vyra_sk_your_key_here" }
+    }
+  }
+}
+```
+
+## Environment
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `VYRA_API_KEY` | — | Your `vyra_sk_…` key (required) |
+| `VYRA_BASE_URL` | `https://creator-networks-sigma.vercel.app` | Override the API origin (local dev/testing) |
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,63 @@
+// Tiny REST client for the Vyra public API (/api/v1). Every MCP tool calls
+// through here so auth, base URL, and error handling live in one place.
+//
+// Config comes from the environment so the same binary works locally and in
+// production:
+//   VYRA_API_KEY   — the brand's `vyra_sk_…` key (required)
+//   VYRA_BASE_URL  — API origin (optional; defaults to production)
+// Current hosting is the Vercel preview domain; swap to the real domain at launch.
+const DEFAULT_BASE_URL = "https://creator-networks-sigma.vercel.app";
+// Resolve the API origin, trimming a trailing slash so path-joining is safe.
+function baseUrl() {
+    const raw = process.env.VYRA_BASE_URL?.trim() || DEFAULT_BASE_URL;
+    return raw.replace(/\/+$/, "");
+}
+// The API key is required for every call; fail loudly if it's missing.
+function apiKey() {
+    const key = process.env.VYRA_API_KEY?.trim();
+    if (!key) {
+        throw new Error("VYRA_API_KEY is not set. Run `npx vyra-mcp connect <your-key>` first.");
+    }
+    return key;
+}
+// Make one authenticated request and unwrap the { data } / { error } envelope.
+// Throws a readable Error on any non-2xx or transport failure — never returns
+// a half-valid result.
+export async function apiRequest(method, path, body) {
+    // Resolve config first so a missing key reports clearly (not as a network
+    // failure, which would be misleading).
+    const url = `${baseUrl()}/api/v1${path}`;
+    const key = apiKey();
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${key}`,
+                "Content-Type": "application/json",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : "network error";
+        throw new Error(`Could not reach Vyra at ${url}: ${reason}`);
+    }
+    // Parse JSON defensively — some error paths may return an empty body.
+    let json = null;
+    const text = await res.text();
+    if (text) {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Vyra returned a non-JSON response (HTTP ${res.status})`);
+        }
+    }
+    if (!res.ok) {
+        const message = json?.error ??
+            `HTTP ${res.status} from Vyra`;
+        throw new Error(message);
+    }
+    return json?.data;
+}

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/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 serve                                     run the MCP server (stdio)
+//   vyra-mcp                                           same as `serve`
+//
+// `serve` is the default so MCP clients can spawn the bare binary.
+import { connect } from "./connect.js";
+import { serve } from "./server.js";
+function getFlag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case "connect": {
+            const key = rest.find((a) => !a.startsWith("--"));
+            if (!key) {
+                console.error("Usage: npx vyra-mcp connect <your-api-key>");
+                process.exitCode = 1;
+                return;
+            }
+            connect(key, getFlag(rest, "--base-url"));
+            return;
+        }
+        case undefined:
+        case "serve":
+            await serve();
+            return;
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.error("Usage: npx vyra-mcp <connect|serve>");
+            process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/connect.js

@@ -0,0 +1,98 @@
+// `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");
+    }
+}
+// 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");
+    }
+}
+// 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) {
+    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);
+        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);
+        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.");
+}

package/dist/server.js

@@ -0,0 +1,127 @@
+// The Vyra MCP server. Exposes the public REST API as MCP tools so an LLM agent
+// (Claude, ChatGPT, any MCP client) can run creator campaigns in plain English.
+//
+// Each tool is a thin wrapper over one /api/v1 endpoint. Money is handled in
+// integer cents end-to-end; the platform margin is never exposed (PRD §18).
+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";
+// 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) {
+    try {
+        const data = await fn();
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
+}
+export function buildServer() {
+    const server = new McpServer({ name: "vyra", version: "0.1.0" });
+    // --- Wallet -------------------------------------------------------------
+    server.registerTool("get_wallet_balance", {
+        title: "Get wallet balance",
+        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")));
+    // --- Campaigns: read ----------------------------------------------------
+    server.registerTool("list_campaigns", {
+        title: "List campaigns",
+        description: "List all of the brand's campaigns with status, budget, and fee details.",
+        inputSchema: {},
+    }, () => run(() => apiRequest("GET", "/campaigns")));
+    server.registerTool("get_campaign", {
+        title: "Get campaign",
+        description: "Get one campaign by id, including its current status.",
+        inputSchema: {
+            campaign_id: z.string().describe("The campaign id"),
+        },
+    }, ({ campaign_id }) => run(() => apiRequest("GET", `/campaigns/${campaign_id}`)));
+    server.registerTool("list_campaign_slots", {
+        title: "List campaign creators",
+        description: "List the creators who joined a campaign, with each submission's status and view count.",
+        inputSchema: {
+            campaign_id: z.string().describe("The campaign id"),
+        },
+    }, ({ campaign_id }) => run(() => apiRequest("GET", `/campaigns/${campaign_id}/slots`)));
+    // --- Submissions --------------------------------------------------------
+    server.registerTool("get_submission", {
+        title: "Get submission",
+        description: "Get one creator submission's status, metrics (views/likes/comments/shares), quality score, cost, and watch-window progress.",
+        inputSchema: {
+            submission_id: z.string().describe("The submission id"),
+        },
+    }, ({ submission_id }) => run(() => apiRequest("GET", `/submissions/${submission_id}`)));
+    // --- Campaigns: write ---------------------------------------------------
+    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(),
+        },
+    }, (args) => run(() => apiRequest("POST", "/campaigns", args)));
+    server.registerTool("activate_campaign", {
+        title: "Activate campaign",
+        description: "Activate a draft campaign: checks funds, reserves budget, and makes it live for creators. Fails if the wallet balance is too low.",
+        inputSchema: {
+            campaign_id: z.string().describe("The campaign id to activate"),
+        },
+    }, ({ campaign_id }) => run(() => apiRequest("POST", `/campaigns/${campaign_id}/activate`)));
+    server.registerTool("pause_campaign", {
+        title: "Pause campaign",
+        description: "Pause a live campaign so no new creators can join. In-progress submissions are unaffected.",
+        inputSchema: {
+            campaign_id: z.string().describe("The campaign id to pause"),
+        },
+    }, ({ campaign_id }) => run(() => apiRequest("POST", `/campaigns/${campaign_id}/pause`)));
+    return server;
+}
+// Start the server on stdio (how MCP clients spawn it as a child process).
+export async function serve() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "vyra-mcp",
+  "version": "0.1.0",
+  "description": "Drive Vyra from Claude, ChatGPT, or any MCP client — manage performance-based creator campaigns in plain English.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "vyra-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}