vyra-mcp 0.2.0 → 0.3.0

package/README.md

@@ -17,13 +17,18 @@ performance-based creator campaigns in plain English.
 
 ## 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/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.3.0",
   "description": "Drive Vyra from Claude, ChatGPT, or any MCP client — manage performance-based creator campaigns in plain English.",
   "license": "MIT",
   "type": "module",