@nestpilot/mcp-app 1.0.0

package/dist/tools/plan-management-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AuthContext } from "./mcp-helpers.js";
+export declare function registerPlanManagementTools(server: McpServer, authCtx?: AuthContext): void;

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

@@ -0,0 +1,196 @@
+/**
+ * Plan management MCP tools — CRUD operations on persisted plans.
+ *
+ * Mirrors the plan management API used by the web app (apps/web/hooks/useApi.ts):
+ *   list_plans, get_plan, get_active_plan, create_saved_plan, save_plan,
+ *   activate_plan, delete_plan, rename_plan, get_plan_components.
+ */
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { proxyGetTool, proxyPostTool, proxyPutTool, proxyDeleteTool, proxyPatchTool, } from "./mcp-helpers.js";
+export function registerPlanManagementTools(server, authCtx) {
+    // ── 1. list_plans ───────────────────────────────────────────────────────
+    registerAppTool(server, "list_plans", {
+        title: "List Plans",
+        description: `Lists all retirement plans saved by the authenticated user.
+
+USE THIS TOOL WHEN THE USER:
+- Asks "What plans do I have?" or "Show me my plans"
+- Wants to pick a plan to view or edit
+- Needs plan IDs for other operations (forecast, scenario, etc.)
+
+REQUIRES authentication — will return an empty list for anonymous users.`,
+        inputSchema: {},
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async () => {
+        return proxyGetTool("/api/plans", undefined, {
+            toolName: "list_plans",
+            authCtx,
+        });
+    });
+    // ── 2. get_plan ─────────────────────────────────────────────────────────
+    registerAppTool(server, "get_plan", {
+        title: "Get Plan",
+        description: `Retrieves a single saved plan by its ID, including all inputs.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to view the details of a specific plan
+- Needs to load a plan before editing or running a forecast`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to retrieve"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId } = args;
+        return proxyGetTool(`/api/plans/${planId}`, undefined, {
+            toolName: "get_plan",
+            authCtx,
+        });
+    });
+    // ── 3. get_active_plan ──────────────────────────────────────────────────
+    registerAppTool(server, "get_active_plan", {
+        title: "Get Active Plan",
+        description: `Retrieves the user's currently active plan.
+
+USE THIS TOOL WHEN THE USER:
+- Asks about "my plan" or "my current plan" without specifying which one
+- Wants to work with their default/active plan
+- Needs the active plan's ID for forecasts or scenarios`,
+        inputSchema: {},
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async () => {
+        return proxyGetTool("/api/plans/active", undefined, {
+            toolName: "get_active_plan",
+            authCtx,
+        });
+    });
+    // ── 4. create_saved_plan ────────────────────────────────────────────────
+    registerAppTool(server, "create_saved_plan", {
+        title: "Create Saved Plan",
+        description: `Creates a new retirement plan and saves it to the database.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to save a new plan after providing their financial details
+- Says "save this plan" or "create a new plan called..."
+- Has provided comprehensive plan data and wants it persisted
+
+Unlike create_plan (which is a stateless calculation), this tool persists the
+plan to the database so it can be retrieved, updated, and used for forecasts.
+
+The inputs should match the PlanContract schema: household, goals, accounts,
+incomeStreams, spendStreams, assumptions, strategy, preferences.`,
+        inputSchema: {
+            name: z.string().describe("Human-readable plan name"),
+            inputs: z
+                .record(z.any())
+                .describe("PlanContract object with all plan data (household, goals, accounts, incomeStreams, etc.)"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { name, inputs } = args;
+        const endpoint = `/api/plans?name=${encodeURIComponent(name)}`;
+        return proxyPostTool(endpoint, inputs, {
+            toolName: "create_saved_plan",
+            authCtx,
+        });
+    });
+    // ── 5. save_plan ────────────────────────────────────────────────────────
+    registerAppTool(server, "save_plan", {
+        title: "Save Plan",
+        description: `Updates an existing saved plan with new inputs.
+
+USE THIS TOOL WHEN THE USER:
+- Has modified their plan and wants to save the changes
+- Says "update my plan" after making changes
+- Wants to overwrite a plan with new data`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to update"),
+            name: z.string().describe("Plan name"),
+            inputs: z
+                .record(z.any())
+                .describe("Updated PlanContract object"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId, name, inputs } = args;
+        const endpoint = `/api/plans/${planId}?name=${encodeURIComponent(name)}`;
+        return proxyPutTool(endpoint, inputs, {
+            toolName: "save_plan",
+            authCtx,
+        });
+    });
+    // ── 6. activate_plan ────────────────────────────────────────────────────
+    registerAppTool(server, "activate_plan", {
+        title: "Activate Plan",
+        description: `Sets a plan as the user's active (default) plan.
+
+USE THIS TOOL WHEN THE USER:
+- Says "make this my active plan" or "switch to plan X"
+- Wants to change which plan is used by default`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to activate"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId } = args;
+        return proxyPostTool(`/api/plans/${planId}/activate`, {}, { toolName: "activate_plan", authCtx });
+    });
+    // ── 7. delete_plan ──────────────────────────────────────────────────────
+    registerAppTool(server, "delete_plan", {
+        title: "Delete Plan",
+        description: `Deletes a saved plan. This is a soft delete and may cascade to associated
+forecasts and scenarios.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to remove a plan they no longer need
+- Says "delete this plan" or "remove plan X"`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to delete"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId } = args;
+        return proxyDeleteTool(`/api/plans/${planId}`, {
+            toolName: "delete_plan",
+            authCtx,
+        });
+    });
+    // ── 8. rename_plan ──────────────────────────────────────────────────────
+    registerAppTool(server, "rename_plan", {
+        title: "Rename Plan",
+        description: `Renames an existing plan.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to change the name of a plan
+- Says "rename this plan to..." or "call it..."`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to rename"),
+            newName: z.string().describe("New name for the plan"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId, newName } = args;
+        return proxyPatchTool(`/api/plans/${planId}`, { name: newName }, { toolName: "rename_plan", authCtx });
+    });
+    // ── 9. get_plan_components ──────────────────────────────────────────────
+    registerAppTool(server, "get_plan_components", {
+        title: "Get Plan Components",
+        description: `Retrieves the financial components attached to a saved plan
+(annuities, pensions, rental income, insurance, etc.).
+
+USE THIS TOOL WHEN THE USER:
+- Asks what components are part of their plan
+- Wants to see add-on financial products in their plan
+- Needs component IDs for scenario overrides (componentOverrides in run_scenario)`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the saved plan"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId } = args;
+        return proxyGetTool(`/api/plans/${planId}/components`, undefined, {
+            toolName: "get_plan_components",
+            authCtx,
+        });
+    });
+}

package/dist/tools/planning-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AuthContext } from "./mcp-helpers.js";
+export declare function registerPlanningTools(server: McpServer, authCtx?: AuthContext): void;

package/dist/tools/planning-tools.js

@@ -0,0 +1,290 @@
+/**
+ * Retirement planning MCP tools — create_plan, run_forecast, run_scenario,
+ * verify_forecast, coach.
+ *
+ * Each tool is a thin facade over a NestPilot Spring Boot API endpoint.
+ * Registered via registerAppTool() so they're discoverable by MCP Apps hosts.
+ */
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { proxyPostTool } from "./mcp-helpers.js";
+export function registerPlanningTools(server, authCtx) {
+    // ── 1. create_plan ────────────────────────────────────────────────────
+    // Quick retirement projection via POST /api/plan/calc
+    registerAppTool(server, "create_plan", {
+        title: "Create Retirement Plan",
+        description: `Creates a quick retirement plan projection. Returns projected balance at retirement, safe withdrawal amount, readiness score, and sustainability years.
+
+USE THIS TOOL WHEN THE USER:
+- Wants a quick retirement projection given basic inputs
+- Asks "Am I on track to retire?" or "How much will I have at retirement?"
+- Provides their age, retirement age, savings balance, and contribution amounts
+- Wants to understand their withdrawal rate feasibility
+
+DO NOT USE when the user has detailed accounts, income streams, or tax data — use run_forecast instead for comprehensive analysis.`,
+        inputSchema: {
+            currentAge: z
+                .number()
+                .int()
+                .min(0)
+                .describe("Current age of the user"),
+            retireAge: z
+                .number()
+                .int()
+                .min(0)
+                .describe("Target retirement age"),
+            lifeExpectancy: z
+                .number()
+                .int()
+                .min(0)
+                .describe("Planning horizon / life expectancy in years"),
+            currentBalance: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Current total retirement savings balance in dollars"),
+            monthlyContribution: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Monthly savings contribution in dollars"),
+            realReturnRate: z
+                .number()
+                .describe("Expected real annual return rate as decimal, e.g. 0.05 for 5%"),
+            withdrawalRate: z
+                .number()
+                .describe("Planned annual withdrawal rate in retirement as decimal, e.g. 0.04 for 4%"),
+            targetAnnualSpending: z
+                .number()
+                .optional()
+                .describe("Desired annual spending in retirement, in dollars"),
+            userId: z
+                .string()
+                .optional()
+                .describe("Optional user ID for auto-filling balance from linked accounts"),
+        },
+        _meta: {
+            ui: {
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        return proxyPostTool("/api/plan/calc", args, {
+            toolName: "create_plan",
+            authCtx,
+        });
+    });
+    // ── 2. run_forecast ───────────────────────────────────────────────────
+    // Comprehensive retirement forecast via POST /api/plan/forecast
+    registerAppTool(server, "run_forecast", {
+        title: "Run Retirement Forecast",
+        description: `Runs a comprehensive deterministic retirement forecast with multi-account, multi-income-stream support. Returns readiness score, yearly projections, portfolio runway, legacy value, and success probability.
+
+USE THIS TOOL WHEN THE USER:
+- Has detailed financial data: multiple accounts (401k, IRA, Roth, taxable), income streams, Social Security
+- Wants year-by-year projections through retirement
+- Asks about portfolio runway or "When will I run out of money?"
+- Wants to consider tax optimization, withdrawal ordering, or Roth conversions
+- Has a spouse and needs household-level analysis
+
+REQUIRES at minimum: currentAge, retirementAge, targetMonthlySpending, at least one account, and at least one income stream.`,
+        inputSchema: {
+            payload: z
+                .record(z.any())
+                .describe(`Full PlanInputExtended object. Required fields: currentAge (int >=18), retirementAge (int >=50), horizonAge (int, default 95), targetMonthlySpending (number), accounts (array of {type, balance, annualContribution?, realReturn?} where type is one of: traditional, roth, taxable, hsa, cash — MUST be lowercase), incomeStreams (array of {type, amountMonthly, startAge?, endAge?} where type is one of: salary, social_security, pension, annuity, rental, other — MUST be lowercase). Optional: socialSecurityFRA, socialSecurityClaimAge, safeWithdrawalRate (default 0.04), effectiveTaxRate (default 0.15), withdrawalStrategy ("taxable_first"|"traditional_first"), filingStatus, spouse, inflationRate (default 0.03), displayMode ("real"|"nominal"), planId.`),
+        },
+        _meta: {
+            ui: {
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        const { payload } = args;
+        return proxyPostTool("/api/plan/forecast", payload, {
+            toolName: "run_forecast",
+            authCtx,
+        });
+    });
+    // ── 3. run_scenario ───────────────────────────────────────────────────
+    // What-if scenario analysis via POST /api/plan/scenario/run
+    registerAppTool(server, "run_scenario", {
+        title: "Run What-If Scenario",
+        description: `Runs a what-if scenario analysis comparing a baseline retirement plan against modified assumptions. Supports plan parameter deltas, component enable/disable overrides, and optional historical market stress tests. Returns baseline vs. candidate comparison with delta metrics.
+
+USE THIS TOOL WHEN THE USER:
+- Asks "What if I retire at 62 instead of 65?"
+- Wants to compare scenarios (e.g., current plan vs. delaying Social Security)
+- Asks about impact of enabling/disabling plan components (annuity, rental income)
+- Wants to stress-test against historical market crashes (2008, dot-com, 1929)
+- Says "How would my plan hold up in a recession?"
+
+REQUIRES: A plan object and at least one override or delta.`,
+        inputSchema: {
+            plan: z
+                .record(z.any())
+                .describe(`PlanContract baseline plan object. Shape: {household: {primary: {age, retireAge, salary?, socialSecurity?}, spouse?}, goals: {retirement: {targetSpending: {amountMonthly}}}, accounts: [...], incomeStreams: [...], taxProfile?, assumptions?, strategy?}`),
+            label: z
+                .string()
+                .optional()
+                .describe("Human-readable label, e.g. 'Retire at 62' or 'Add annuity'"),
+            planId: z
+                .string()
+                .optional()
+                .describe("UUID of saved plan; used to load persisted components for override"),
+            overrides: z
+                .object({
+                planDeltas: z
+                    .array(z.object({
+                    path: z
+                        .string()
+                        .describe("JSON pointer to field, e.g. 'household.primary.retireAge'"),
+                    to: z.any().describe("New value for the field"),
+                }))
+                    .optional()
+                    .describe("Field-level overrides for the candidate scenario"),
+                componentOverrides: z
+                    .array(z.object({
+                    componentId: z
+                        .string()
+                        .describe("UUID of plan component"),
+                    enabled: z
+                        .boolean()
+                        .optional()
+                        .describe("Override enabled state"),
+                    paramsOverride: z
+                        .record(z.any())
+                        .optional()
+                        .describe("Parameter overrides"),
+                }))
+                    .optional()
+                    .describe("Ephemeral component state changes"),
+                stressTest: z
+                    .object({
+                    scenarioId: z
+                        .string()
+                        .describe("e.g. '2008_CRISIS', '1929_CRASH', 'DOT_COM_BUST'"),
+                    applyTo: z
+                        .string()
+                        .optional()
+                        .describe("'EQUITY' or 'ALL'. Default: EQUITY"),
+                    align: z
+                        .string()
+                        .optional()
+                        .describe("'PLAN_START', 'RETIREMENT', or 'CUSTOM_YEAR'"),
+                    customStartYear: z
+                        .number()
+                        .int()
+                        .optional()
+                        .describe("Only when align='CUSTOM_YEAR'"),
+                })
+                    .optional()
+                    .describe("Optional historical market stress test"),
+            })
+                .optional()
+                .describe("Bundle of overrides: plan deltas, component toggles, and/or stress test"),
+        },
+        _meta: {
+            ui: {
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        return proxyPostTool("/api/plan/scenario/run", args, { toolName: "run_scenario", authCtx });
+    });
+    // ── 4. verify_forecast ─────────────────────────────────────────────────
+    // Forecast verification via POST /api/plan/forecast/verify
+    registerAppTool(server, "verify_forecast", {
+        title: "Verify Forecast",
+        description: `Runs forecast verification and returns a verification packet — a structured, auditable record of the inputs, calculation trace, and verdict. Used to verify advisor projections or double-check personal planning scenarios.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to verify numbers from their financial advisor
+- Asks for a "second opinion" on a retirement projection
+- Wants an auditable record of their retirement calculation
+- Says "check my advisor's numbers" or "verify this projection"
+
+DO NOT USE for new projections — use run_forecast instead. This tool is specifically for verification of existing projections.`,
+        inputSchema: {
+            payload: z
+                .record(z.any())
+                .describe(`PlanInputExtended payload for /api/plan/forecast/verify. Same shape as run_forecast: Required fields: currentAge (int >=18), retirementAge (int >=50), horizonAge (int, default 95), targetMonthlySpending (number), accounts (array of {type, balance, annualContribution?, realReturn?} where type MUST be lowercase: traditional, roth, taxable, hsa, cash), incomeStreams (array of {type, amountMonthly, startAge?, endAge?} where type MUST be lowercase: salary, social_security, pension, annuity, rental, other).`),
+        },
+        _meta: {
+            ui: {
+                resourceUri: "ui://verification-packet/verification-packet.html",
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        const { payload } = args;
+        return proxyPostTool("/api/plan/forecast/verify", payload, {
+            toolName: "verify_forecast",
+            authCtx,
+        });
+    });
+    // ── 5. coach ───────────────────────────────────────────────────────────
+    // AI coaching via POST /api/spring_ai/coach
+    registerAppTool(server, "coach", {
+        title: "Retirement Coach",
+        description: `Provides AI-powered retirement coaching — conversational guidance, explanations of retirement concepts, and personalized next-step suggestions.
+
+USE THIS TOOL WHEN THE USER:
+- Asks about retirement concepts ("What is a Roth conversion?", "How does the 4% rule work?")
+- Wants personalized guidance after describing their situation
+- Asks "What does this mean for me?" after running a forecast or scenario
+- Has open-ended questions that need narrative answers, not calculations
+
+DO NOT USE for calculations — use run_forecast or create_plan instead.
+DO NOT USE for Medicare enrollment — use medicare-guardian instead.
+DO NOT USE for verifying advisor numbers — use verify_forecast instead.`,
+        inputSchema: {
+            content: z
+                .string()
+                .describe("Prompt content for retirement coach guidance"),
+            userId: z.string().optional().describe("User ID for personalization"),
+            planId: z
+                .string()
+                .optional()
+                .describe("Plan ID for context-aware coaching"),
+            schemaVersion: z.string().optional().describe("Schema version"),
+        },
+        _meta: {
+            ui: {
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        return proxyPostTool("/api/spring_ai/coach", args, { toolName: "coach", authCtx });
+    });
+    // ── 6. comprehensive_plan ──────────────────────────────────────────────
+    // Combined coach insights + forecast in one call via POST /api/plan/comprehensive
+    registerAppTool(server, "comprehensive_plan", {
+        title: "Comprehensive Plan Analysis",
+        description: `Runs a combined coach-insights + forecast analysis in a single call.
+Returns both coaching guidance and detailed forecast projections together.
+
+USE THIS TOOL WHEN THE USER:
+- Wants a full retirement analysis with both narrative insights and numbers
+- Says "give me the full picture" or "analyze my plan comprehensively"
+- Needs coach guidance alongside forecast projections in one response
+- Wants to save time vs calling coach + run_forecast separately
+
+REQUIRES the same PlanContract payload as run_forecast.`,
+        inputSchema: {
+            payload: z
+                .record(z.any())
+                .describe(`Full PlanContract object. Same shape as run_forecast payload: currentAge, retirementAge, horizonAge, targetMonthlySpending, accounts (array), incomeStreams (array). Optional: socialSecurityFRA, socialSecurityClaimAge, safeWithdrawalRate, effectiveTaxRate, withdrawalStrategy, filingStatus, spouse, inflationRate, displayMode, planId.`),
+        },
+        _meta: {
+            ui: {
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        const { payload } = args;
+        return proxyPostTool("/api/plan/comprehensive", payload, {
+            toolName: "comprehensive_plan",
+            authCtx,
+        });
+    });
+}

package/dist/tools/proposal-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AuthContext } from "./mcp-helpers.js";
+export declare function registerProposalTools(server: McpServer, authCtx?: AuthContext): void;