@nestpilot/mcp-app 1.0.0

package/dist/tools/scenario-management-tools.js

@@ -0,0 +1,136 @@
+/**
+ * Scenario management MCP tools.
+ *
+ * Provides CRUD wrappers for saved what-if scenarios.
+ */
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { proxyDeleteTool, proxyGetTool, proxyPostTool, } from "./mcp-helpers.js";
+export function registerScenarioManagementTools(server, authCtx) {
+    registerAppTool(server, "save_scenario", {
+        title: "Save Scenario",
+        description: `Persists a what-if scenario for a user and optionally a plan.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to save a scenario they just ran
+- Needs to keep scenario deltas/overrides for future comparison`,
+        inputSchema: {
+            label: z.string().describe("Human-readable scenario name"),
+            deltas: z
+                .array(z.record(z.any()))
+                .optional()
+                .describe("Legacy delta list for backward compatibility"),
+            overrides: z
+                .record(z.any())
+                .optional()
+                .describe("Scenario override bundle (planDeltas, componentOverrides, componentAdditions)"),
+            bundle: z
+                .record(z.any())
+                .optional()
+                .describe("Optional computed bundle snapshot"),
+            forecastId: z
+                .string()
+                .optional()
+                .describe("Optional linked forecast ID"),
+            planId: z.string().optional().describe("Optional saved plan UUID"),
+            componentAdditions: z
+                .array(z.object({
+                componentId: z.string().describe("Product component ID, e.g. 'highpoint365.v1'"),
+                version: z.string().optional().describe("Component version"),
+                name: z.string().describe("Display name"),
+                params: z.record(z.any()).describe("Configuration parameters"),
+                enabled: z.boolean().optional().default(true),
+            }))
+                .optional()
+                .describe("FEAT-0079: New financial components to add in this scenario (e.g. annuities, insurance). Merged into overrides.componentAdditions."),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const payload = { ...args };
+        // FEAT-0079: Merge top-level componentAdditions into overrides bundle
+        if (payload.componentAdditions && Array.isArray(payload.componentAdditions)) {
+            const overrides = payload.overrides ?? {};
+            overrides.componentAdditions = payload.componentAdditions;
+            payload.overrides = overrides;
+            delete payload.componentAdditions;
+        }
+        return proxyPostTool("/api/scenarios/save", payload, {
+            toolName: "save_scenario",
+            authCtx,
+        });
+    });
+    registerAppTool(server, "list_scenarios", {
+        title: "List Scenarios",
+        description: `Lists saved scenarios. If planId is provided, scopes to that plan.
+
+USE THIS TOOL WHEN THE USER:
+- Asks what scenarios they have saved
+- Needs a scenario ID before loading or deleting one`,
+        inputSchema: {
+            planId: z
+                .string()
+                .optional()
+                .describe("Optional plan UUID to filter scenarios"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId } = (args ?? {});
+        const params = planId ? { planId } : undefined;
+        return proxyGetTool("/api/scenarios", params, {
+            toolName: "list_scenarios",
+            authCtx,
+        });
+    });
+    registerAppTool(server, "get_scenario", {
+        title: "Get Scenario",
+        description: `Retrieves one saved scenario by ID.`,
+        inputSchema: {
+            scenarioId: z.string().describe("UUID of the saved scenario"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { scenarioId } = args;
+        return proxyGetTool(`/api/scenarios/${encodeURIComponent(scenarioId)}`, undefined, {
+            toolName: "get_scenario",
+            authCtx,
+        });
+    });
+    registerAppTool(server, "delete_scenario", {
+        title: "Delete Scenario",
+        description: `Deletes a saved scenario by ID.`,
+        inputSchema: {
+            scenarioId: z.string().describe("UUID of the saved scenario"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { scenarioId } = args;
+        return proxyDeleteTool(`/api/scenarios/${encodeURIComponent(scenarioId)}`, {
+            toolName: "delete_scenario",
+            authCtx,
+        });
+    });
+    /** @feature FEAT-0079 */
+    registerAppTool(server, "promote_scenario", {
+        title: "Promote Scenario to Baseline",
+        description: `Promotes a scenario to become the client's new baseline plan.
+
+Applies all scenario overrides (plan deltas, component changes, component additions) permanently to the plan. A backup scenario is auto-created before promotion for rollback safety.
+
+USE THIS TOOL WHEN:
+- The client has unlocked a proposal and wants to adopt the advisor's recommended changes
+- The advisor or client wants to make a scenario the new baseline
+- The user says "adopt this plan", "promote scenario", or "apply these changes"
+
+SAFETY: A backup of the current baseline is created automatically. The promoted scenario is soft-deleted after promotion.
+
+GATED: Plan owner only.`,
+        inputSchema: {
+            planId: z.string().uuid().describe("UUID of the plan"),
+            scenarioId: z.string().uuid().describe("UUID of the scenario to promote"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId, scenarioId } = args;
+        return proxyPostTool(`/api/plans/${encodeURIComponent(planId)}/scenarios/${encodeURIComponent(scenarioId)}/promote`, {}, { toolName: "promote_scenario", authCtx });
+    });
+}