@apex-inc/mcp-server 0.8.0 → 0.9.0

package/dist/tools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveProject, getActiveProject, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
+import { apiGet, apiPost, apiPatch, apiDelete, postWithIdempotency, setActiveWorkspace, getActiveWorkspace, setActiveOrg, getActiveOrg, getUserContext } from "./api-client.js";
 const APEX = "∧ Apex";
 /**
  * MOBX-006 — stable synthetic visitor id for agent-fired events.
@@ -942,7 +942,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             // under `untracked`). Stamp the per-process synthetic visitor
             // id + timestamp so agent-fired events actually count.
             const result = await apiPost("/api/events", {
-                projectKey: process.env.APEX_PROJECT_KEY || "default",
+                workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
                 userId: "mcp-agent",
                 events: [
                     {
@@ -1012,7 +1012,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             await apiPost("/api/identity/stitch", {
                 visitorId: `mcp-${email}`,
                 email,
-                projectKey: process.env.APEX_PROJECT_KEY || "default",
+                workspaceKey: (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY) || "default",
                 metadata: { name, company, ...metadata, source: "mcp" },
             });
             return {
@@ -1027,7 +1027,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         description: `${APEX} — Read the workspace's canonical Schema (data dictionary): entities, their fields, which fields are wired (observed in live data) vs not, surface coverage, and any canonical mappings. Use to see what variables/attributes a workspace has and what's still unwired before authoring comms or segments.`,
         schema: z.object({}),
         handler: async () => {
-            const dict = await apiGet("/api/data-dictionary");
+            const dict = await apiGet("/api/schema");
             const lines = [];
             for (const entity of Object.values(dict.entities)) {
                 lines.push(`\n${entity.label}  {{${entity.key}.<field>}}`);
@@ -1058,7 +1058,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 .describe("Canonical snake_case name (e.g. 'first_name'), or null to clear"),
         }),
         handler: async ({ entityKey, fieldName, canonicalName, }) => {
-            const res = await apiPost("/api/data-dictionary/map", { entityKey, fieldName, canonicalName: canonicalName ?? null });
+            const res = await apiPost("/api/schema/map", { entityKey, fieldName, canonicalName: canonicalName ?? null });
             const mapped = res.data?.canonicalName;
             return {
                 content: [
@@ -1124,48 +1124,51 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     list_projects: {
-        description: "List all projects available to your API key. Use this to see which projects you can work with.",
+        description: "List all workspaces available to your API key. Use this to see which workspaces you can work with.",
         schema: z.object({}),
         handler: async () => {
-            const projects = await apiGet("/api/projects");
-            const current = getActiveProject();
-            if (!projects.length) {
+            // NOTE: `/api/projects` is the PERMANENT alias path this tool has
+            // shipped against — it returns the flat row shape below. Do not
+            // point at `/api/workspaces` (different response shape).
+            const workspaces = await apiGet("/api/projects");
+            const current = getActiveWorkspace();
+            if (!workspaces.length) {
                 return {
                     content: [{
                             type: "text",
-                            text: "No projects found for this API key.",
+                            text: "No workspaces found for this API key.",
                         }],
                 };
             }
-            const lines = projects.map((p) => {
-                const active = p.projectKey === current ? " ← active" : "";
-                return `  ${p.projectKey} — ${p.name} (${p.url})${active}`;
+            const lines = workspaces.map((p) => {
+                const active = p.workspaceKey === current ? " ← active" : "";
+                return `  ${p.workspaceKey} — ${p.name} (${p.url})${active}`;
             });
             return {
                 content: [{
                         type: "text",
-                        text: [`Projects (${projects.length}):`, ...lines].join("\n"),
+                        text: [`Workspaces (${workspaces.length}):`, ...lines].join("\n"),
                     }],
             };
         },
     },
     switch_project: {
-        description: "Switch the active project for this session. All subsequent API calls will use this project.",
+        description: "Switch the active workspace for this session. All subsequent API calls will use this workspace.",
         schema: z.object({
-            projectKey: z.string().describe("The project key to switch to"),
+            workspaceKey: z.string().describe("The workspace key to switch to"),
         }),
         handler: async (args) => {
-            setActiveProject(args.projectKey);
+            setActiveWorkspace(args.workspaceKey);
             return {
                 content: [{
                         type: "text",
-                        text: `Switched to project: ${args.projectKey}. All subsequent calls will use this project.`,
+                        text: `Switched to workspace: ${args.workspaceKey}. All subsequent calls will use this workspace.`,
                     }],
             };
         },
     },
     list_orgs: {
-        description: "List all organizations you have access to, with their projects. Use this to see which orgs and projects are available.",
+        description: "List all organizations you have access to, with their workspaces. Use this to see which orgs and workspaces are available.",
         schema: z.object({}),
         handler: async () => {
             const ctx = getUserContext();
@@ -1180,8 +1183,8 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             const activeOrg = getActiveOrg();
             const lines = ctx.orgs.map((org) => {
                 const active = org.orgId === activeOrg ? " ← active" : "";
-                const projects = org.projects.map((p) => `    ${p.projectKey} — ${p.name}`).join("\n");
-                return `  ${org.orgName} (${org.orgId}, ${org.role})${active}\n${projects || "    (no projects)"}`;
+                const workspaces = org.workspaces.map((p) => `    ${p.workspaceKey} — ${p.name}`).join("\n");
+                return `  ${org.orgName} (${org.orgId}, ${org.role})${active}\n${workspaces || "    (no workspaces)"}`;
             });
             return {
                 content: [{
@@ -1192,7 +1195,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         },
     },
     switch_org: {
-        description: "Switch the active organization. This also switches to the first project in that org.",
+        description: "Switch the active organization. This also switches to the first workspace in that org.",
         schema: z.object({
             orgId: z.string().describe("The organization ID to switch to (from list_orgs)"),
         }),
@@ -1219,12 +1222,12 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 };
             }
             setActiveOrg(args.orgId);
-            const project = getActiveProject();
-            const projectInfo = project ? `, active project: ${project}` : "";
+            const workspace = getActiveWorkspace();
+            const projectInfo = workspace ? `, active workspace: ${workspace}` : "";
             return {
                 content: [{
                         type: "text",
-                        text: `Switched to org: ${org.orgName} (${org.projects.length} project${org.projects.length !== 1 ? "s" : ""})${projectInfo}.`,
+                        text: `Switched to org: ${org.orgName} (${org.workspaces.length} workspace${org.workspaces.length !== 1 ? "s" : ""})${projectInfo}.`,
                     }],
             };
         },
@@ -1375,7 +1378,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     //
     // Merchant-scoped tools for managing an affiliate program through the
     // Apex Partner Network. Every tool authenticates via the caller's
-    // active project + API key (same pattern as experiments / comms).
+    // active workspace + API key (same pattern as experiments / comms).
     // Partner-facing flows (self-signup, portal) + admin Fraud Ops are
     // intentionally not wrapped — they require different auth.
     list_partner_programs: {
@@ -1550,7 +1553,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 const tag = f.isCustom ? " (custom)" : "";
                 return `• ${kind}: ${display}${tag} — source: ${f.source}`;
             }).join("\n");
-            return { content: [{ type: "text", text: `Fees for ${data.projectKey}:\n\n${lines}\n\nFull data:\n${JSON.stringify(data, null, 2)}` }] };
+            return { content: [{ type: "text", text: `Fees for ${data.workspaceKey}:\n\n${lines}\n\nFull data:\n${JSON.stringify(data, null, 2)}` }] };
         },
     },
     vouch_for_partner: {
@@ -1570,7 +1573,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
     // Pair with the AudienceActivationWizard (Layer 2) to give agents
     // a way to wire up audience instrumentation without leaving the
     // editor. Both tools are PROJECT-SCOPED via the api-client's
-    // active-project context — the merchant's CLI run pins which
+    // active-workspace context — the merchant's CLI run pins which
     // workspace they're acting on.
     wire_audience_seed: {
         description: `${APEX} — Wire up the events and traits a campaign audience seed depends on. Use this when the merchant says "wire up the active customers audience" or after the AudienceActivationWizard's Screen 1 hands off to Cursor. Returns the per-event/trait code snippets, the file recommendations, and fires a test event with is_test=1 so the wizard's polling loop confirms the wiring landed end-to-end. Idempotent: calling twice does NOT double-instrument; the agent should still review existing code before adding the snippet.`,
@@ -1588,13 +1591,13 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 .describe("When true (default), fires a test event with is_test=1 for each event the seed depends on. The wizard's poll loop sees these and advances. Set to false if the agent only wants to read the snippets without writing test data."),
         }),
         handler: async ({ seedId, framework = "typescript", fireTestEvent = true, }) => {
-            const projectKey = getActiveProject() || process.env.APEX_PROJECT_KEY;
-            if (!projectKey) {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "No active project. Call set_active_project first or set APEX_PROJECT_KEY.",
+                            text: "No active workspace. Call set_active_project first or set APEX_PROJECT_KEY.",
                         },
                     ],
                 };
@@ -1656,7 +1659,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                     ? `## Test events fired\nFired test events for: ${firedTests.join(", ")}. The wizard's polling loop will see these and advance. Confirm the merchant fires REAL events from production code paths before relying on the audience.`
                     : `## Test events\nNo test events fired (per fireTestEvent=false). Run the wizard's "Send a test event" button manually after wiring.`,
                 ``,
-                `Project: ${projectKey}`,
+                `Workspace: ${workspaceKey}`,
             ].join("\n");
             return { content: [{ type: "text", text: summary }] };
         },
@@ -1677,13 +1680,13 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 .describe("When true (default), fires a test event with is_test=1 for each NON-AUTO-FIRED event the audience depends on. Auto-fired events (pageview, click, etc.) are skipped — they're already firing automatically and don't need a synthetic test."),
         }),
         handler: async ({ audienceId, framework = "typescript", fireTestEvent = true, }) => {
-            const projectKey = getActiveProject() || process.env.APEX_PROJECT_KEY;
-            if (!projectKey) {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "No active project. Call set_active_project first or set APEX_PROJECT_KEY.",
+                            text: "No active workspace. Call set_active_project first or set APEX_PROJECT_KEY.",
                         },
                     ],
                 };
@@ -1752,7 +1755,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
             else {
                 sections.push(`\n## Test events\nNo test events fired (per fireTestEvent=false). Run the wizard's "Send a test event" button manually after wiring.`);
             }
-            sections.push(`\nProject: ${projectKey}`);
+            sections.push(`\nWorkspace: ${workspaceKey}`);
             return { content: [{ type: "text", text: sections.join("\n") }] };
         },
     },
@@ -1764,13 +1767,13 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 .describe("Audience id (the workspace's audience record, not the seed). Use list_audiences first to find it."),
         }),
         handler: async ({ audienceId }) => {
-            const projectKey = getActiveProject() || process.env.APEX_PROJECT_KEY;
-            if (!projectKey) {
+            const workspaceKey = getActiveWorkspace() || (process.env.APEX_WORKSPACE_KEY || process.env.APEX_PROJECT_KEY);
+            if (!workspaceKey) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "No active project. Call set_active_project first or set APEX_PROJECT_KEY.",
+                            text: "No active workspace. Call set_active_project first or set APEX_PROJECT_KEY.",
                         },
                     ],
                 };
@@ -1799,7 +1802,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
                 preview && preview.matchingCount === 0
                     ? `\n## Diagnosis\nZero matches. Most likely causes:\n  1. Events the predicate references aren't firing yet from the merchant's codebase. Run \`wire_audience_seed\` if this is a starter audience, or check the predicate's event names against your codebase.\n  2. The predicate's window (\`last_n_days\`, \`ever\`) is too narrow.\n  3. End-user identity isn't being stitched. Each \`apex.track()\` call must include \`endUserId\` in its data payload, or be preceded by an \`identify()\` call.\n`
                     : "",
-                `\nProject: ${projectKey}`,
+                `\nWorkspace: ${workspaceKey}`,
             ].join("\n");
             return { content: [{ type: "text", text: summary }] };
         },
@@ -1968,7 +1971,7 @@ Events fired through this tool carry a stable synthetic visitorId (mcp-agent-*,
         description: `${APEX} — READ-ONLY. Returns the current Set up Apex state for the active workspace: which steps the merchant has marked complete or skipped, plus the live signal flags (snippet installed, mobile live, sender domain verified, etc.). Use to answer "where am I in onboarding?" or to surface "your next step is X" recommendations. WRITE tools (complete_setup_step, skip_setup_step) are deliberately NOT exposed pending a server-enforced confirmation nonce.`,
         schema: z.object({}),
         handler: async () => {
-            // The active project key is encoded in the x-apex-project header
+            // The active workspace key is encoded in the x-apex-workspace header
             // that apiGet sends automatically.
             const data = await apiGet("/api/setup-state");
             const { overrides, signal, workspaceKey } = data.data;
@@ -2007,7 +2010,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
                 .describe("Include archived sources. Defaults to false."),
         }),
         handler: async ({ includeArchived }) => {
-            const proj = getActiveProject();
+            const proj = getActiveWorkspace();
             const qs = includeArchived ? "?includeArchived=true" : "";
             const json = await apiGet(`/api/workspaces/${proj}/data-sources${qs}`);
             const sources = json.data ?? [];
@@ -2027,7 +2030,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             name: z.string().describe("Display name, e.g. 'Marketing site' or 'Backend API'."),
         }),
         handler: async ({ kind, name }) => {
-            const proj = getActiveProject();
+            const proj = getActiveWorkspace();
             const json = await apiPost(`/api/workspaces/${proj}/data-sources`, { kind, name });
             const s = json.data;
             return { content: [{ type: "text", text: `✓ Created data source **${s.name}** (${s.kind}) — ${s.status} · \`${s.id}\`` }] };
@@ -2039,7 +2042,7 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             id: z.string().describe("The data source id (ds_...)."),
         }),
         handler: async ({ id }) => {
-            const proj = getActiveProject();
+            const proj = getActiveWorkspace();
             const json = await apiGet(`/api/workspaces/${proj}/data-sources/${encodeURIComponent(id)}/health`);
             const h = json.data;
             return { content: [{ type: "text", text: `# ${h.kind} source ${h.id}\n\n- status: **${h.status}**\n- first seen: ${h.firstSeenAt ?? "never"}\n- last seen: ${h.lastSeenAt ?? "never"}` }] };
@@ -2105,13 +2108,13 @@ _Suggest the next step the user should tackle based on what's incomplete in the
         description: `${APEX} — Live wiring verification for the active workspace: which canonical events have been received (tier: waiting → detected → verified), which identify traits (first_name, email, …) are arriving, per-data-source status, and which journey/communication templates are Ready to run. Call this AFTER instrumenting tracking code to verify your own work — iterate until each wired event reports "detected". Presence-only: never returns end-user values.`,
         schema: z.object({}),
         handler: async () => {
-            const projectKey = getActiveProject();
-            if (!projectKey) {
+            const workspaceKey = getActiveWorkspace();
+            if (!workspaceKey) {
                 return {
-                    content: [{ type: "text", text: "No active project. Use switch_project first (or set APEX_PROJECT_KEY)." }],
+                    content: [{ type: "text", text: "No active workspace. Use switch_project first (or set APEX_PROJECT_KEY)." }],
                 };
             }
-            const json = await apiGet(`/api/workspaces/${encodeURIComponent(projectKey)}/readiness`);
+            const json = await apiGet(`/api/workspaces/${encodeURIComponent(workspaceKey)}/readiness`);
             const d = json.data;
             const eventLines = d.events.map((e) => `- ${e.name}: ${e.tier} (${e.count.toLocaleString()} events, platforms: ${e.platforms.join("/") || "—"})${e.observedFields?.length ? ` — fields seen: ${e.observedFields.join(", ")}` : ""}`);
             const traitLines = d.traits.map((t) => `- ${t.name}: ${t.present ? "arriving" : "not seen"}${t.inferredType ? ` (${t.inferredType})` : ""}`);
@@ -2129,7 +2132,52 @@ _Suggest the next step the user should tackle based on what's incomplete in the
             return {
                 content: [{
                         type: "text",
-                        text: `# Wiring status — ${projectKey}\n\n## Milestones\n${milestones.map((m) => `- ${m}`).join("\n")}\n\n## Events received\n${eventLines.join("\n") || "_none yet_"}\n\n## Identify traits\n${traitLines.join("\n") || "_none yet_"}\n\n## Data sources\n${sourceLines.join("\n") || "_none yet_"}\n\n## Templates\n${templateLines.join("\n") || "_none derivable yet_"}`,
+                        text: `# Wiring status — ${workspaceKey}\n\n## Milestones\n${milestones.map((m) => `- ${m}`).join("\n")}\n\n## Events received\n${eventLines.join("\n") || "_none yet_"}\n\n## Identify traits\n${traitLines.join("\n") || "_none yet_"}\n\n## Data sources\n${sourceLines.join("\n") || "_none yet_"}\n\n## Templates\n${templateLines.join("\n") || "_none derivable yet_"}`,
+                    }],
+            };
+        },
+    },
+    propose_wiring_plan: {
+        description: `${APEX} — Report the Apex Spec instrumentation opportunities you found by SCANNING the merchant's codebase (auth flows → identify + user_signed_up, checkout → purchase events, forms → form_submit, app purchases → in_app_purchase, server order paths → order_placed, …). Call this BEFORE wiring: the plan appears on the merchant's setup page as pending lights, each flipping green when its first real event arrives. Structure your scan report in three sections: (1) ALREADY WIRED — events the repo already instruments (include them here with wired: true; they're awaiting their first heartbeat), (2) GAPS TO WIRE — the work you propose, (3) WON'T WIRE + WHY — opportunities you're deliberately skipping (e.g. a server event with no backend, or a form that already fires a richer dedicated event). Then instrument each gap where the truth lives and verify with get_wiring_status. Scan first; never ask the merchant to enumerate events for you.`,
+        schema: z.object({
+            events: z
+                .array(z.object({
+                name: z
+                    .string()
+                    .describe("Canonical snake_case event name from the Apex Spec (use get_event_spec), or a custom snake_case name."),
+                surface: z
+                    .enum(["web", "mobile", "server"])
+                    .describe("Where this event should fire FROM — wire each event where the truth lives."),
+                note: z
+                    .string()
+                    .optional()
+                    .describe("Short pointer to where you found the opportunity, e.g. 'checkout/confirm.ts handlePayment()'."),
+                wired: z
+                    .boolean()
+                    .optional()
+                    .describe("True when the repo ALREADY instruments this event (awaiting its first heartbeat) — the merchant's board labels it 'wired' instead of 'agent plan'."),
+            }))
+                .min(1)
+                .describe("Every instrumentation opportunity found in the scan — both already-wired events (wired: true) and the gaps you propose to wire."),
+            summary: z.string().optional().describe("One-paragraph scan summary for the merchant — include what you're deliberately NOT wiring and why."),
+        }),
+        handler: async (args) => {
+            const workspaceKey = getActiveWorkspace();
+            if (!workspaceKey) {
+                return {
+                    content: [{ type: "text", text: "No active workspace. Use switch_project first (or set APEX_PROJECT_KEY)." }],
+                };
+            }
+            const json = await apiPost(`/api/workspaces/${encodeURIComponent(workspaceKey)}/wiring-plan`, {
+                events: args.events,
+                summary: args.summary,
+                source: "mcp",
+            });
+            const lines = json.data.events.map((e) => `- ${e.name} (${e.surface})${e.wired ? " — already wired, awaiting first heartbeat" : ""}`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `# Wiring plan proposed — ${workspaceKey}\n\nThe merchant's setup page now shows ${json.data.events.length} pending event light${json.data.events.length === 1 ? "" : "s"}:\n${lines.join("\n")}\n\nNext: instrument each gap where it happens in the code (smallest change, never commit), then call get_wiring_status until every light reports "detected".`,
                     }],
             };
         },