@nestpilot/mcp-app 1.0.0

package/dist/tools/proposal-tools.js

@@ -0,0 +1,428 @@
+/**
+ * Proposal generation MCP tool — FEAT-0068
+ *
+ * Orchestrates existing NestPilot APIs to assemble a client-ready advisor proposal:
+ *   1. POST /api/plans/{planId}/summary/generate       — plan summary PDF
+ *   2. POST /api/advisor/clients/{clientUserId}/proposals — create proposal record
+ *   3. (optional) POST …/proposals/{id}/release         — release to client
+ *
+ * Gated to Advisor tier via EntitlementService / policy engine (FEAT-0063).
+ *
+ * @feature FEAT-0068
+ */
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { nestpilotClient } from "../nestpilot-client.js";
+import { toCallToolResult } from "./mcp-helpers.js";
+// ── Helpers ─────────────────────────────────────────────────────────────
+function buildAuthHeaders(authCtx) {
+    const headers = {};
+    if (authCtx?.bearerToken) {
+        headers.Authorization = `Bearer ${authCtx.bearerToken}`;
+    }
+    if (authCtx?.userId) {
+        headers["X-User-ID"] = authCtx.userId;
+    }
+    return headers;
+}
+function isError(result) {
+    return result.error === true;
+}
+// ── Tool registration ────────────────────────────────────────────────────
+export function registerProposalTools(server, authCtx) {
+    registerAppTool(server, "generate_proposal", {
+        title: "Generate Advisor Proposal",
+        description: `Assembles a client-ready retirement planning proposal for an advisor.
+
+Orchestrates three steps:
+1. Generates a plan summary PDF via SummaryController.
+2. Creates a structured proposal record linked to the plan and client.
+3. Optionally releases the proposal to the client immediately.
+
+USE THIS TOOL WHEN THE ADVISOR:
+- Wants to package analysis into a formal deliverable for a client
+- Has reviewed scenarios/optimizations and is ready to share findings
+- Asks "create a proposal for my client" or "generate a proposal"
+- Wants to bundle forecast + Roth/SS analysis into one document
+
+DO NOT USE for internal analysis — use run_forecast or optimize_roth_conversion instead.
+DO NOT USE if the advisor has not reviewed the plan first.
+
+SAFETY GATES:
+- Proposal is NOT released unless autoRelease is explicitly true.
+- Advisor must confirm before release (prompt if autoRelease is true).
+
+GATED: Advisor tier only.`,
+        inputSchema: {
+            planId: z
+                .string()
+                .uuid()
+                .describe("Plan ID to base the proposal on"),
+            clientUserId: z
+                .string()
+                .uuid()
+                .describe("Client user ID the proposal is for"),
+            title: z
+                .string()
+                .describe("Proposal title — shown to the client"),
+            subtitle: z
+                .string()
+                .optional()
+                .describe("Optional subtitle or tagline"),
+            advisorNotes: z
+                .string()
+                .optional()
+                .describe("Custom advisor notes to include in the proposal"),
+            includeScenarios: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Scenario IDs to include in the proposal comparison"),
+            includeRothAnalysis: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Include Roth conversion analysis summary"),
+            includeSsAnalysis: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Include Social Security claiming analysis summary"),
+            unlockPriceCents: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .default(0)
+                .describe("Client unlock price in cents (0 = free)"),
+            autoRelease: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Release proposal to client immediately. Advisor must explicitly set true."),
+        },
+        _meta: {
+            ui: {
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        const { planId, clientUserId, title, subtitle, advisorNotes, includeScenarios, includeRothAnalysis = false, includeSsAnalysis = false, unlockPriceCents = 0, autoRelease = false, } = args;
+        const authHeaders = buildAuthHeaders(authCtx);
+        // ── Step 1: Generate plan summary PDF ───────────────────────────
+        const summaryResult = await nestpilotClient.post(`/api/plans/${planId}/summary/generate`, {}, { headers: authHeaders });
+        if (isError(summaryResult)) {
+            return toCallToolResult({
+                error: true,
+                step: "summary_generation",
+                message: summaryResult.message ?? "Failed to generate plan summary",
+                detail: summaryResult,
+            }, true);
+        }
+        const summaryUrl = summaryResult.pdfUrl ??
+            summaryResult.downloadUrl ??
+            null;
+        // ── Step 2: Build explanation markdown from advisor notes ────────
+        const explanationParts = [];
+        if (advisorNotes) {
+            explanationParts.push(`## Advisor Notes\n\n${advisorNotes}`);
+        }
+        if (includeRothAnalysis) {
+            explanationParts.push("## Roth Conversion Analysis\n\nRoth conversion optimization was performed. See attached analysis.");
+        }
+        if (includeSsAnalysis) {
+            explanationParts.push("## Social Security Claiming Analysis\n\nSS claiming optimization was performed. See attached analysis.");
+        }
+        const explanationMarkdown = explanationParts.length > 0 ? explanationParts.join("\n\n") : undefined;
+        // ── Step 3: Create proposal record ──────────────────────────────
+        const proposalPayload = {
+            planId,
+            title,
+            subtitle: subtitle ?? null,
+            unlockPriceCents,
+            impactSummary: {
+                summaryPdfUrl: summaryUrl,
+                includesRothAnalysis: includeRothAnalysis,
+                includesSsAnalysis: includeSsAnalysis,
+            },
+            explanationMarkdown: explanationMarkdown ?? null,
+            actionDetails: [],
+            scenarioIds: includeScenarios ?? [],
+            tags: [
+                "mcp-generated",
+                ...(includeRothAnalysis ? ["roth-analysis"] : []),
+                ...(includeSsAnalysis ? ["ss-analysis"] : []),
+            ],
+        };
+        const createResult = await nestpilotClient.post(`/api/advisor/clients/${clientUserId}/proposals`, proposalPayload, { headers: authHeaders });
+        if (isError(createResult)) {
+            return toCallToolResult({
+                error: true,
+                step: "proposal_creation",
+                message: createResult.message ?? "Failed to create proposal record",
+                detail: createResult,
+                summaryGenerated: !!summaryUrl,
+                summaryUrl,
+            }, true);
+        }
+        const proposalId = createResult.id ??
+            createResult.proposalId;
+        // ── Step 4: Optional auto-release ───────────────────────────────
+        let releaseResult = null;
+        if (autoRelease && proposalId) {
+            releaseResult = await nestpilotClient.post(`/api/advisor/clients/${clientUserId}/proposals/${proposalId}/release`, {}, { headers: authHeaders });
+            if (isError(releaseResult)) {
+                // Proposal was created but release failed — return partial success
+                return toCallToolResult({
+                    proposalId,
+                    status: "draft",
+                    warning: "Proposal was created but automatic release failed. Release it manually from the Proposal Manager.",
+                    releaseError: releaseResult.message,
+                    summaryUrl,
+                    proposal: createResult,
+                });
+            }
+        }
+        // ── Assemble response ────────────────────────────────────────────
+        const status = autoRelease && releaseResult ? "released" : "draft";
+        const response = {
+            proposalId,
+            status,
+            planId,
+            clientUserId,
+            title,
+            summaryUrl,
+            autoReleased: autoRelease && status === "released",
+            evidencePacket: {
+                planSummaryGenerated: true,
+                summaryUrl,
+                includesRothAnalysis: includeRothAnalysis,
+                includesSsAnalysis: includeSsAnalysis,
+                scenariosIncluded: includeScenarios?.length ?? 0,
+                generatedAt: new Date().toISOString(),
+                assumptions: [
+                    "Plan summary generated from current saved plan state.",
+                    "All projections are estimates and not guaranteed.",
+                    "Tax calculations use current-year rates and may change.",
+                ],
+                disclaimers: [
+                    "This proposal is for educational purposes only.",
+                    "Consult a licensed financial advisor before making investment decisions.",
+                    "Past performance does not guarantee future results.",
+                ],
+            },
+            proposal: createResult,
+            releaseResult: releaseResult ?? undefined,
+        };
+        return toCallToolResult(response);
+    });
+    /**
+     * FEAT-0079: Build an improvement proposal from a scenario with component additions.
+     *
+     * Orchestrates the full advisor improvement flow:
+     *   1. Save scenario with componentAdditions on client's plan
+     *   2. Run resilience on baseline (or reuse existing report)
+     *   3. Run resilience on scenario
+     *   4. Create proposal linking scenario + both resilience reports
+     *   5. Optionally auto-release
+     *
+     * @feature FEAT-0079
+     */
+    registerAppTool(server, "build_improvement_proposal", {
+        title: "Build Improvement Proposal",
+        description: `Creates an advisor proposal that demonstrates plan improvement via scenario comparison.
+
+Orchestrates five steps:
+1. Saves a scenario with component additions (e.g. annuity, insurance) on the client's plan.
+2. Runs resilience stress test on the baseline plan.
+3. Runs resilience stress test on the scenario (with added components).
+4. Creates a proposal linking the scenario and both resilience reports (before/after).
+5. Optionally releases the proposal to the client.
+
+The client sees a before/after resilience grade comparison when they unlock the proposal, and can "adopt" the scenario to make it their new baseline.
+
+USE THIS TOOL WHEN THE ADVISOR:
+- Has identified improvements for a client's plan (e.g. adding an annuity)
+- Wants to show the client a before/after comparison
+- Says "build an improvement proposal" or "show the client how this helps"
+- Wants to bundle scenario + resilience comparison into a proposal
+
+DO NOT USE for simple verbal proposals — use generate_proposal instead.
+
+GATED: Advisor tier only.`,
+        inputSchema: {
+            planId: z.string().uuid().describe("UUID of the client's plan"),
+            clientUserId: z.string().uuid().describe("Client user UUID"),
+            title: z.string().describe("Proposal title shown to the client"),
+            subtitle: z.string().optional().describe("Optional subtitle"),
+            scenarioLabel: z
+                .string()
+                .describe("Name for the improvement scenario (e.g. 'Add Nationwide HighPoint 365')"),
+            componentAdditions: z
+                .array(z.object({
+                componentId: z.string().describe("Product component ID"),
+                version: z.string().optional(),
+                name: z.string().describe("Display name"),
+                params: z.record(z.any()).describe("Configuration parameters"),
+                enabled: z.boolean().optional().default(true),
+            }))
+                .describe("Financial components to add in this scenario"),
+            planDeltas: z
+                .array(z.record(z.any()))
+                .optional()
+                .describe("Optional plan input overrides (e.g. adjust retire age, spending)"),
+            advisorNotes: z.string().optional().describe("Advisor notes in markdown"),
+            unlockPriceCents: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .default(0)
+                .describe("Client unlock price in cents (0 = free)"),
+            autoRelease: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Release proposal to client immediately"),
+            existingBaselineReportId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Reuse an existing baseline resilience report ID instead of running a new one"),
+        },
+        _meta: { ui: { visibility: ["model", "app"] } },
+    }, async (args) => {
+        const { planId, clientUserId, title, subtitle, scenarioLabel, componentAdditions, planDeltas, advisorNotes, unlockPriceCents = 0, autoRelease = false, existingBaselineReportId, } = args;
+        const authHeaders = buildAuthHeaders(authCtx);
+        // ── Step 1: Save scenario with componentAdditions ────────────────
+        const scenarioPayload = {
+            label: scenarioLabel,
+            planId,
+            overrides: {
+                planDeltas: planDeltas ?? [],
+                componentOverrides: [],
+                componentAdditions,
+            },
+        };
+        const scenarioResult = await nestpilotClient.post("/api/scenarios/save", scenarioPayload, { headers: authHeaders });
+        if (isError(scenarioResult)) {
+            return toCallToolResult({
+                error: true,
+                step: "save_scenario",
+                message: scenarioResult.message ?? "Failed to save scenario",
+                detail: scenarioResult,
+            }, true);
+        }
+        const scenarioId = scenarioResult.id ??
+            scenarioResult.scenarioId;
+        if (!scenarioId) {
+            return toCallToolResult({ error: true, step: "save_scenario", message: "Scenario saved but no ID returned" }, true);
+        }
+        // ── Step 2: Get plan data for resilience runs ───────────────────
+        const plan = await nestpilotClient.get(`/api/plans/${planId}`, undefined, {
+            headers: authHeaders,
+        });
+        if (isError(plan)) {
+            return toCallToolResult({
+                error: true,
+                step: "load_plan",
+                message: plan.message ?? "Failed to load plan",
+                scenarioId,
+            }, true);
+        }
+        // ── Step 3: Run baseline resilience (or reuse existing) ────────
+        let baselineReportId = existingBaselineReportId ?? null;
+        if (!baselineReportId) {
+            const baselineRes = await nestpilotClient.post("/api/resilience/run", { plan, planId, saveReport: true }, { headers: authHeaders, timeout: 120_000 });
+            if (isError(baselineRes)) {
+                return toCallToolResult({
+                    error: true,
+                    step: "baseline_resilience",
+                    message: baselineRes.message ?? "Failed to run baseline resilience",
+                    scenarioId,
+                }, true);
+            }
+            baselineReportId = baselineRes.reportId ?? null;
+        }
+        // ── Step 4: Run scenario resilience ─────────────────────────────
+        const scenarioRes = await nestpilotClient.post("/api/resilience/run", { plan, planId, scenarioId, saveReport: true }, { headers: authHeaders, timeout: 120_000 });
+        if (isError(scenarioRes)) {
+            return toCallToolResult({
+                error: true,
+                step: "scenario_resilience",
+                message: scenarioRes.message ?? "Failed to run scenario resilience",
+                scenarioId,
+                baselineReportId,
+            }, true);
+        }
+        const scenarioReportId = scenarioRes.reportId ?? null;
+        // ── Step 5: Create proposal with resilience links ───────────────
+        const explanationParts = [];
+        if (advisorNotes) {
+            explanationParts.push(`## Advisor Notes\n\n${advisorNotes}`);
+        }
+        explanationParts.push(`## Plan Improvement\n\nThis proposal includes a scenario ("${scenarioLabel}") ` +
+            `that demonstrates how adding ${componentAdditions.length} component(s) improves your plan's resilience.`);
+        const proposalPayload = {
+            planId,
+            title,
+            subtitle: subtitle ?? null,
+            unlockPriceCents,
+            impactSummary: {
+                baselineGrade: plan.overallGrade ?? null,
+                scenarioGrade: scenarioRes.overallGrade ?? null,
+                componentsAdded: componentAdditions.map((c) => c.name ?? c.componentId),
+            },
+            explanationMarkdown: explanationParts.join("\n\n"),
+            actionDetails: componentAdditions.map((c) => `Add ${c.name ?? c.componentId} to your plan`),
+            scenarioIds: [scenarioId],
+            tags: ["mcp-generated", "improvement-proposal"],
+            baselineResilienceReportId: baselineReportId,
+            scenarioResilienceReportId: scenarioReportId,
+        };
+        const createResult = await nestpilotClient.post(`/api/advisor/clients/${clientUserId}/proposals`, proposalPayload, { headers: authHeaders });
+        if (isError(createResult)) {
+            return toCallToolResult({
+                error: true,
+                step: "proposal_creation",
+                message: createResult.message ?? "Failed to create proposal",
+                scenarioId,
+                baselineReportId,
+                scenarioReportId,
+            }, true);
+        }
+        const proposalId = createResult.id ??
+            createResult.proposalId;
+        // ── Step 6: Optional auto-release ───────────────────────────────
+        let releaseResult = null;
+        if (autoRelease && proposalId) {
+            releaseResult = await nestpilotClient.post(`/api/advisor/clients/${clientUserId}/proposals/${proposalId}/release`, {}, { headers: authHeaders });
+            if (isError(releaseResult)) {
+                return toCallToolResult({
+                    proposalId,
+                    status: "draft",
+                    warning: "Proposal created but auto-release failed. Release manually.",
+                    releaseError: releaseResult.message,
+                    scenarioId,
+                    baselineReportId,
+                    scenarioReportId,
+                });
+            }
+        }
+        const status = autoRelease && releaseResult ? "released" : "draft";
+        return toCallToolResult({
+            proposalId,
+            status,
+            planId,
+            clientUserId,
+            title,
+            scenarioId,
+            baselineReportId,
+            scenarioReportId,
+            autoReleased: autoRelease && status === "released",
+            componentsAdded: componentAdditions.map((c) => c.name ?? c.componentId),
+            message: `Improvement proposal ${status === "released" ? "released" : "created as draft"} successfully. ` +
+                `Scenario "${scenarioLabel}" saved with ${componentAdditions.length} component(s). ` +
+                `Resilience comparison: baseline report ${baselineReportId}, scenario report ${scenarioReportId}.`,
+        });
+    });
+}

package/dist/tools/report-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 registerReportTools(server: McpServer, authCtx?: AuthContext): void;

package/dist/tools/report-tools.js

@@ -0,0 +1,245 @@
+/**
+ * Report generation MCP tools — generate_retirement_report.
+ *
+ * Orchestrates plan retrieval, forecast execution, scenario loading,
+ * and PDF generation via the generate_report.py script.
+ */
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { nestpilotClient } from "../nestpilot-client.js";
+import { resolveSavedPlanId } from "./forecast-management-tools.js";
+import { toCallToolResult } from "./mcp-helpers.js";
+const execFileAsync = promisify(execFile);
+// Canonical script location: skills/retirement-report/scripts/ (single-source convention).
+// Falls back to local mcp-app/scripts/ for backward compatibility.
+const SKILL_SCRIPTS_DIR = path.resolve(import.meta.dirname, "..", "..", "..", "skills", "retirement-report", "scripts");
+const LOCAL_SCRIPTS_DIR = path.join(import.meta.dirname, "..", "scripts");
+async function resolveScriptsDir() {
+    try {
+        await fs.access(path.join(SKILL_SCRIPTS_DIR, "generate_report.py"));
+        return SKILL_SCRIPTS_DIR;
+    }
+    catch {
+        return LOCAL_SCRIPTS_DIR;
+    }
+}
+function buildAuthHeaders(authCtx) {
+    const headers = {};
+    if (authCtx?.bearerToken) {
+        headers.Authorization = `Bearer ${authCtx.bearerToken}`;
+    }
+    if (authCtx?.userId) {
+        headers["X-User-ID"] = authCtx.userId;
+    }
+    return headers;
+}
+/**
+ * Builds a forecast payload from a saved plan object.
+ */
+function buildForecastPayload(plan, planId) {
+    const household = plan.household;
+    const primary = household?.primary;
+    const goals = plan.goals;
+    const retirement = goals?.retirement;
+    const targetSpending = retirement?.targetSpending;
+    return {
+        currentAge: primary?.age,
+        retirementAge: primary?.retireAge,
+        horizonAge: primary?.horizonAge ?? 95,
+        targetMonthlySpending: targetSpending?.amountMonthly,
+        accounts: plan.accounts,
+        incomeStreams: plan.incomeStreams,
+        spendStreams: plan.spendStreams,
+        filingStatus: household?.filingStatus,
+        spouse: household?.spouse,
+        socialSecurityFRA: primary?.socialSecurity,
+        socialSecurityClaimAge: primary?.socialSecurityClaimAge,
+        strategy: plan.strategy,
+        taxProfile: plan.taxProfile,
+        assumptions: plan.assumptions,
+        planId,
+    };
+}
+export function registerReportTools(server, authCtx) {
+    registerAppTool(server, "generate_retirement_report", {
+        title: "Generate Retirement Report",
+        description: `Generates a comprehensive retirement planning PDF report for a saved plan. Loads the plan, runs a forecast, optionally includes saved scenarios, and produces a professional PDF with plan details, charts, projections, and recommendations.
+
+USE THIS TOOL WHEN THE USER:
+- Wants a PDF document summarizing their retirement plan
+- Asks to "create a retirement report" or "generate a retirement report"
+- Needs a shareable/printable retirement forecast
+- Wants to export their plan and forecast to PDF
+- Requests a retirement readiness report in document format
+
+REQUIRES a saved plan (planId or active plan). Returns the PDF file path.`,
+        inputSchema: {
+            planId: z
+                .string()
+                .optional()
+                .describe("UUID of the saved plan. Alias values 'default', 'active', or 'current' use the active plan. Omit to use the active plan."),
+            clientName: z
+                .string()
+                .optional()
+                .describe("Client name for personalizing the report header (e.g., 'John & Jane Doe')"),
+            includeScenarios: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("Whether to include saved scenario comparisons in the report (default: true)"),
+            includeResilience: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe("Whether to include the latest resilience stress-test assessment in the report (default: true). Uses saved report if available; skips silently if none exists."),
+            outputPath: z
+                .string()
+                .optional()
+                .describe("Custom output path for the PDF. If omitted, generates in a temp directory."),
+        },
+        _meta: {
+            ui: {
+                visibility: ["model", "app"],
+            },
+        },
+    }, async (args) => {
+        const { planId: rawPlanId, clientName, includeScenarios = true, includeResilience = true, outputPath, } = args;
+        // 1. Resolve plan ID
+        const resolved = await resolveSavedPlanId(rawPlanId, authCtx);
+        if (resolved.errorResult)
+            return resolved.errorResult;
+        if (!resolved.planId) {
+            return toCallToolResult({
+                error: true,
+                code: 400,
+                message: "No plan ID provided and no active plan found. Create or activate a saved plan first.",
+            }, true);
+        }
+        const planId = resolved.planId;
+        // 2. Get plan details
+        const plan = await nestpilotClient.get(`/api/plans/${planId}`, undefined, {
+            headers: buildAuthHeaders(authCtx),
+        });
+        if (plan.error) {
+            return toCallToolResult({
+                error: true,
+                code: plan.code ?? 500,
+                message: plan.message ?? `Failed to load plan ${planId}`,
+            }, true);
+        }
+        // 3. Run forecast
+        const forecastPayload = buildForecastPayload(plan, planId);
+        const forecast = await nestpilotClient.post("/api/plan/forecast", forecastPayload, {
+            headers: buildAuthHeaders(authCtx),
+            timeout: 60_000,
+        });
+        if (forecast.error) {
+            return toCallToolResult({
+                error: true,
+                code: forecast.code ?? 500,
+                message: forecast.message ?? "Failed to run forecast",
+            }, true);
+        }
+        // 4. Optionally load scenarios
+        let scenarios = null;
+        if (includeScenarios) {
+            const scenarioList = await nestpilotClient.get("/api/scenarios", {
+                planId,
+            }, {
+                headers: buildAuthHeaders(authCtx),
+            });
+            if (!scenarioList.error && Array.isArray(scenarioList)) {
+                scenarios = scenarioList;
+            }
+        }
+        // 4b. Optionally load resilience report (saved, not live)
+        let resilienceReport = null;
+        if (includeResilience) {
+            try {
+                const resList = await nestpilotClient.get("/api/resilience/reports", {
+                    planId,
+                }, {
+                    headers: buildAuthHeaders(authCtx),
+                });
+                if (!resList.error && Array.isArray(resList) && resList.length > 0) {
+                    resilienceReport = resList[0];
+                }
+            }
+            catch (e) {
+                // Non-fatal — skip resilience section silently
+                console.warn("[report-tools] Failed to load resilience report:", e);
+            }
+        }
+        // 5. Write temp files and run Python script
+        const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "nestpilot-report-"));
+        const planFile = path.join(tmpDir, "plan.json");
+        const forecastFile = path.join(tmpDir, "forecast.json");
+        const pdfPath = outputPath ?? path.join(tmpDir, `retirement_report_${planId.slice(0, 8)}.pdf`);
+        await fs.writeFile(planFile, JSON.stringify(plan, null, 2));
+        await fs.writeFile(forecastFile, JSON.stringify(forecast, null, 2));
+        const scriptsDir = await resolveScriptsDir();
+        const pythonArgs = [
+            path.join(scriptsDir, "generate_report.py"),
+            "--output",
+            pdfPath,
+            "--plan-data",
+            planFile,
+            "--forecast-data",
+            forecastFile,
+        ];
+        if (clientName) {
+            pythonArgs.push("--client-name", clientName);
+        }
+        if (scenarios && Array.isArray(scenarios)) {
+            const scenariosFile = path.join(tmpDir, "scenarios.json");
+            await fs.writeFile(scenariosFile, JSON.stringify(scenarios, null, 2));
+            pythonArgs.push("--scenarios-data", scenariosFile);
+        }
+        if (resilienceReport) {
+            const resilienceFile = path.join(tmpDir, "resilience.json");
+            await fs.writeFile(resilienceFile, JSON.stringify(resilienceReport, null, 2));
+            pythonArgs.push("--resilience-data", resilienceFile);
+        }
+        try {
+            const { stdout, stderr } = await execFileAsync("python", pythonArgs, {
+                timeout: 120_000,
+            });
+            if (stderr && stderr.trim()) {
+                console.warn("[report-tools] Python stderr:", stderr);
+            }
+            // Verify PDF was created
+            try {
+                await fs.access(pdfPath);
+            }
+            catch {
+                return toCallToolResult({
+                    error: true,
+                    message: `PDF generation completed but file not found at ${pdfPath}. Python output: ${stdout}`,
+                }, true);
+            }
+            const stats = await fs.stat(pdfPath);
+            return toCallToolResult({
+                success: true,
+                pdfPath,
+                fileSizeBytes: stats.size,
+                planId,
+                includesScenarios: scenarios !== null,
+                includesResilience: resilienceReport !== null,
+                message: `Retirement report generated successfully: ${pdfPath}`,
+            });
+        }
+        catch (e) {
+            const error = e;
+            return toCallToolResult({
+                error: true,
+                message: `PDF generation failed: ${error.message}`,
+                stderr: error.stderr,
+            }, true);
+        }
+    });
+}

package/dist/tools/scenario-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 registerScenarioManagementTools(server: McpServer, authCtx?: AuthContext): void;