@nestpilot/mcp-app 1.0.0

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

@@ -0,0 +1,357 @@
+/**
+ * Local Plan Tools — MCP tool registrations for NESTPILOT_MODE=local.
+ *
+ * Replaces the cloud-proxy planning tools with local-first alternatives:
+ *  - CRUD operations use LocalPlanStore (encrypted ~/.nestpilot/plans/)
+ *  - Compute operations (forecast, scenario, coach) scrub PII and call cloud
+ *  - Cached results enable offline access for previously computed forecasts
+ *
+ * @feature FEAT-0087
+ */
+import { registerAppTool, } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { toCallToolResult } from "./mcp-helpers.js";
+import { scrubPII, validateNoPII } from "../src/local/pii-scrubber.js";
+// ── Tool registration ────────────────────────────────────────────────────
+/**
+ * Registers local-mode MCP tools on the server.
+ * These tools handle data locally and delegate compute to the cloud.
+ */
+export function registerLocalPlanTools(server, store, computeClient) {
+    // ── 1. create_plan (local) ──────────────────────────────────────────
+    registerAppTool(server, "create_plan", {
+        title: "Create Retirement Plan",
+        description: `Creates a new retirement plan stored locally on your machine (~/.nestpilot/plans/).
+Your financial data never leaves your computer. Only PII-free mathematical inputs are sent to the cloud for computation.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to create a new retirement plan
+- Provides financial details (age, accounts, income, spending)
+- Says "help me plan for retirement" or "create a plan"`,
+        inputSchema: {
+            currentAge: z.number().int().min(18).describe("Current age"),
+            retirementAge: z.number().int().min(50).describe("Target retirement age"),
+            horizonAge: z.number().int().optional().describe("Planning horizon age (default: 95)"),
+            targetMonthlySpending: z.number().describe("Monthly spending target in retirement"),
+            accounts: z
+                .array(z.record(z.any()))
+                .optional()
+                .describe("Array of retirement accounts: {type, balance, annualContribution?, realReturn?}"),
+            incomeStreams: z
+                .array(z.record(z.any()))
+                .optional()
+                .describe("Array of income streams: {type, amountMonthly, startAge?, endAge?}"),
+            payload: z.record(z.any()).optional().describe("Full plan payload (alternative to individual fields)"),
+        },
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async (args) => {
+        try {
+            const planData = args.payload
+                ?? args;
+            const localPlan = await store.create(planData);
+            return toCallToolResult({
+                planId: localPlan.id,
+                message: `Plan created and stored locally (${localPlan.id}). Your data is encrypted on your machine.`,
+                plan: localPlan.plan,
+                version: localPlan.version,
+                created: localPlan.created,
+            });
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Failed to create plan: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 2. list_plans (local) ───────────────────────────────────────────
+    registerAppTool(server, "list_plans", {
+        title: "List Local Plans",
+        description: `Lists all retirement plans stored locally on your machine.
+Works fully offline — no internet required.`,
+        inputSchema: {},
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async () => {
+        try {
+            const plans = await store.list();
+            return toCallToolResult({
+                plans,
+                count: plans.length,
+                message: plans.length > 0
+                    ? `Found ${plans.length} local plan(s).`
+                    : "No plans found. Use create_plan to get started.",
+            });
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Failed to list plans: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 3. get_plan (local) ─────────────────────────────────────────────
+    registerAppTool(server, "get_plan", {
+        title: "Get Plan Details",
+        description: `Retrieves full details of a locally stored retirement plan.
+Works fully offline — no internet required.`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to retrieve"),
+        },
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async (args) => {
+        try {
+            const { planId } = args;
+            const localPlan = await store.get(planId);
+            return toCallToolResult({
+                planId: localPlan.id,
+                plan: localPlan.plan,
+                version: localPlan.version,
+                created: localPlan.created,
+                updated: localPlan.updated,
+                metadata: localPlan.metadata,
+            });
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Failed to get plan: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 4. save_plan (local) ────────────────────────────────────────────
+    registerAppTool(server, "save_plan", {
+        title: "Save Plan",
+        description: `Updates and saves an existing retirement plan locally.
+Works fully offline — no internet required.`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to update"),
+            plan: z.record(z.any()).describe("Updated plan data"),
+        },
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async (args) => {
+        try {
+            const { planId, plan } = args;
+            const updated = await store.save(planId, plan);
+            return toCallToolResult({
+                planId: updated.id,
+                version: updated.version,
+                updated: updated.updated,
+                message: "Plan saved successfully.",
+            });
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Failed to save plan: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 5. delete_plan (local) ──────────────────────────────────────────
+    registerAppTool(server, "delete_plan", {
+        title: "Delete Plan",
+        description: `Permanently deletes a locally stored retirement plan and its cached data.
+Works fully offline — no internet required.`,
+        inputSchema: {
+            planId: z.string().describe("UUID of the plan to delete"),
+        },
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async (args) => {
+        try {
+            const { planId } = args;
+            await store.delete(planId);
+            return toCallToolResult({
+                message: `Plan ${planId} deleted.`,
+            });
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Failed to delete plan: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 6. run_forecast (local → cloud compute) ────────────────────────
+    registerAppTool(server, "run_forecast", {
+        title: "Run Retirement Forecast",
+        description: `Runs a comprehensive retirement forecast. Your plan data stays local — only PII-free mathematical inputs (ages, dollar amounts, rates) are sent to the NestPilot compute cloud.
+
+USE THIS TOOL WHEN THE USER:
+- Wants year-by-year retirement projections
+- Asks about portfolio runway or "When will I run out of money?"
+- Has a saved plan and wants to run numbers
+
+Requires internet connectivity for cloud compute. Cached results are returned if offline.`,
+        inputSchema: {
+            planId: z.string().optional().describe("UUID of a saved plan to forecast"),
+            payload: z.record(z.any()).optional().describe("Full plan payload (alternative to planId)"),
+        },
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async (args) => {
+        try {
+            const { planId, payload } = args;
+            // Load plan from store or use inline payload
+            let planData;
+            if (planId) {
+                const localPlan = await store.get(planId);
+                planData = localPlan.plan;
+            }
+            else if (payload) {
+                planData = payload;
+            }
+            else {
+                return toCallToolResult({ error: true, message: "Provide either planId or payload." }, true);
+            }
+            // Scrub PII before cloud call
+            const { payload: scrubbed, removedFields } = scrubPII(planData);
+            if (!validateNoPII(scrubbed)) {
+                return toCallToolResult({
+                    error: true,
+                    message: "PII validation failed — payload may still contain personal information. Please review plan data.",
+                }, true);
+            }
+            if (removedFields.length > 0) {
+                console.log(`[local] PII scrubber removed ${removedFields.length} field(s): ${removedFields.join(", ")}`);
+            }
+            // Call cloud compute
+            const result = await computeClient.forecast(scrubbed);
+            if (result.error) {
+                // Try cached result
+                if (planId) {
+                    const cached = await store.getCachedForecast(planId);
+                    if (cached) {
+                        return toCallToolResult({
+                            ...cached,
+                            _cached: true,
+                            _cacheNote: "Cloud compute unavailable — showing cached forecast result.",
+                            _cloudError: result.message,
+                        });
+                    }
+                }
+                return toCallToolResult({ error: true, message: result.message }, true);
+            }
+            // Cache result for offline access
+            if (planId && result.data) {
+                await store.cacheForecast(planId, result.data).catch((e) => {
+                    console.warn("[local] Failed to cache forecast:", e);
+                });
+            }
+            return toCallToolResult(result.data);
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Forecast failed: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 7. run_scenario (local → cloud compute) ────────────────────────
+    registerAppTool(server, "run_scenario", {
+        title: "Run What-If Scenario",
+        description: `Runs a what-if scenario comparing a baseline plan against modified assumptions.
+Your plan data stays local — only PII-free inputs are sent to the cloud.
+
+USE THIS TOOL WHEN THE USER:
+- Asks "What if I retire at 62 instead of 65?"
+- Wants to compare scenarios
+- Wants to stress-test against historical market events`,
+        inputSchema: {
+            plan: z.record(z.any()).describe("Baseline plan object"),
+            label: z.string().optional().describe("Scenario label"),
+            planId: z.string().optional().describe("UUID of saved plan for caching"),
+            overrides: z.record(z.any()).optional().describe("Scenario overrides"),
+        },
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async (args) => {
+        try {
+            const { plan, label, planId, overrides } = args;
+            // Scrub PII from the plan portion
+            const { payload: scrubbedPlan } = scrubPII(plan);
+            if (!validateNoPII(scrubbedPlan)) {
+                return toCallToolResult({ error: true, message: "PII validation failed on scenario plan." }, true);
+            }
+            const scenarioPayload = {
+                plan: scrubbedPlan,
+                label,
+                overrides,
+            };
+            const result = await computeClient.scenario(scenarioPayload);
+            if (result.error) {
+                return toCallToolResult({ error: true, message: result.message }, true);
+            }
+            // Cache scenario result
+            if (planId && result.data) {
+                await store
+                    .cacheScenario(planId, label ?? "untitled", result.data)
+                    .catch((e) => {
+                    console.warn("[local] Failed to cache scenario:", e);
+                });
+            }
+            return toCallToolResult(result.data);
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Scenario failed: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 8. coach (local → cloud compute) ───────────────────────────────
+    registerAppTool(server, "coach", {
+        title: "Retirement Coach",
+        description: `AI-powered retirement coaching guidance. Your conversation context is sent to the cloud for AI processing, but plan data is scrubbed of PII first.
+
+USE THIS TOOL WHEN THE USER:
+- Asks about retirement concepts
+- Wants personalized guidance
+- Has open-ended financial questions`,
+        inputSchema: {
+            content: z.string().describe("Coaching question or request"),
+            planId: z.string().optional().describe("UUID of plan for context"),
+        },
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async (args) => {
+        try {
+            const { content, planId } = args;
+            const coachPayload = { content };
+            // Add plan context if available (PII-scrubbed)
+            if (planId) {
+                try {
+                    const localPlan = await store.get(planId);
+                    const { payload: scrubbedPlan } = scrubPII(localPlan.plan);
+                    coachPayload.planContext = scrubbedPlan;
+                }
+                catch {
+                    // Plan not found — continue without context
+                }
+            }
+            const result = await computeClient.coach(coachPayload);
+            if (result.error) {
+                return toCallToolResult({ error: true, message: result.message }, true);
+            }
+            return toCallToolResult(result.data);
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Coach failed: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+    // ── 9. status (local-only) ─────────────────────────────────────────
+    registerAppTool(server, "nestpilot_status", {
+        title: "NestPilot Status",
+        description: `Shows the status of your local NestPilot installation including plan count, data directory, cloud connectivity, and disk usage.`,
+        inputSchema: {},
+        _meta: {
+            ui: { visibility: ["model", "app"] },
+        },
+    }, async () => {
+        try {
+            const plans = await store.list();
+            const cloudReachable = await computeClient.healthCheck();
+            return toCallToolResult({
+                mode: "local",
+                dataDir: store["dataDir"],
+                planCount: plans.length,
+                cloudReachable,
+                cloudStatus: cloudReachable ? "connected" : "offline (cached results available)",
+                message: `NestPilot local mode: ${plans.length} plan(s), cloud ${cloudReachable ? "connected" : "offline"}.`,
+            });
+        }
+        catch (e) {
+            return toCallToolResult({ error: true, message: `Status check failed: ${e instanceof Error ? e.message : String(e)}` }, true);
+        }
+    });
+}

package/dist/tools/mcp-helpers.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared MCP tool helpers — response formatting, backend proxy,
+ * contract validation, policy gates, and provenance annotation.
+ *
+ * FEAT-0056: Adds contract lookup, policy evaluation, and provenance
+ * envelope to the tool dispatch pipeline.
+ *
+ * @feature FEAT-0056
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type UserRole } from "../src/policy/policy-engine.js";
+/** Per-request authentication context threaded through the server factory. */
+export interface AuthContext {
+    userId: string;
+    bearerToken?: string;
+}
+/**
+ * Wraps any value into a CallToolResult with a single text content block.
+ */
+export declare function toCallToolResult(payload: unknown, isError?: boolean): CallToolResult;
+export interface DispatchOptions {
+    /** Tool name for contract lookup and policy check. */
+    toolName?: string;
+    /** Actor/user ID for policy evaluation. */
+    actorId?: string;
+    /** User role for policy evaluation. */
+    role?: UserRole;
+    /** Auth context for forwarding JWT / user identity to backend. */
+    authCtx?: AuthContext;
+}
+/**
+ * POSTs to a NestPilot backend endpoint and returns a CallToolResult.
+ * For plan endpoints (/api/plan/*), normalizes enum type fields to lowercase.
+ */
+export declare function proxyPostTool(endpoint: string, args: Record<string, unknown>, opts?: DispatchOptions): Promise<CallToolResult>;
+/**
+ * GETs from a NestPilot backend endpoint and returns a CallToolResult.
+ */
+export declare function proxyGetTool(endpoint: string, params?: Record<string, string>, opts?: DispatchOptions): Promise<CallToolResult>;
+/**
+ * PUTs to a NestPilot backend endpoint and returns a CallToolResult.
+ * For plan endpoints (/api/plan/*), normalizes enum type fields to lowercase.
+ */
+export declare function proxyPutTool(endpoint: string, args: Record<string, unknown>, opts?: DispatchOptions): Promise<CallToolResult>;
+/**
+ * DELETEs from a NestPilot backend endpoint and returns a CallToolResult.
+ */
+export declare function proxyDeleteTool(endpoint: string, opts?: DispatchOptions): Promise<CallToolResult>;
+/**
+ * PATCHes to a NestPilot backend endpoint and returns a CallToolResult.
+ */
+export declare function proxyPatchTool(endpoint: string, args: Record<string, unknown>, opts?: DispatchOptions): Promise<CallToolResult>;

package/dist/tools/mcp-helpers.js

@@ -0,0 +1,177 @@
+import { nestpilotClient } from "../nestpilot-client.js";
+import { lookupContract, } from "../src/contracts/tool-contract-registry.js";
+import { annotateWithProvenance } from "../src/contracts/provenance.js";
+import { evaluatePolicy, } from "../src/policy/policy-engine.js";
+// ── Response helpers ─────────────────────────────────────────────────────
+/**
+ * Wraps any value into a CallToolResult with a single text content block.
+ */
+export function toCallToolResult(payload, isError = false) {
+    return {
+        isError,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload),
+            },
+        ],
+    };
+}
+// ── Payload normalization ────────────────────────────────────────────────
+/**
+ * Normalizes plan payloads before sending to the backend.
+ * The backend uses @JsonCreator with exact lowercase matching for
+ * AccountType (traditional, roth, taxable, hsa, cash) and
+ * IncomeType (salary, social_security, pension, annuity, rental, other).
+ * AI models sometimes send UPPERCASE variants, so we defensively lowercase them.
+ */
+function normalizePlanPayload(args) {
+    const clone = structuredClone(args);
+    // Normalize accounts[].type
+    if (Array.isArray(clone.accounts)) {
+        for (const account of clone.accounts) {
+            if (account && typeof account === "object" && "type" in account) {
+                const a = account;
+                if (typeof a.type === "string") {
+                    a.type = a.type.toLowerCase();
+                }
+            }
+        }
+    }
+    // Normalize incomeStreams[].type
+    if (Array.isArray(clone.incomeStreams)) {
+        for (const stream of clone.incomeStreams) {
+            if (stream && typeof stream === "object" && "type" in stream) {
+                const s = stream;
+                if (typeof s.type === "string") {
+                    s.type = s.type.toLowerCase();
+                }
+            }
+        }
+    }
+    return clone;
+}
+// ── Policy denial response ───────────────────────────────────────────────
+function policyDenialResult(decision) {
+    return toCallToolResult({
+        error: true,
+        code: 403,
+        message: `Policy denied: ${decision.reasonCodes.join(", ")}`,
+        policyDecision: decision,
+    }, true);
+}
+// ── Auth header builder ─────────────────────────────────────────────────
+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 runPipeline(opts) {
+    let contract;
+    if (opts.toolName) {
+        const lookup = lookupContract(opts.toolName);
+        if (lookup.found) {
+            contract = lookup.contract;
+        }
+    }
+    if (contract) {
+        const policyCtx = {
+            actorId: opts.actorId ?? opts.authCtx?.userId ?? "anonymous",
+            role: opts.role ?? (opts.authCtx?.bearerToken ? "authenticated" : "anonymous"),
+            toolName: opts.toolName,
+        };
+        const decision = evaluatePolicy(policyCtx);
+        if (decision.decision === "deny") {
+            return { denied: policyDenialResult(decision) };
+        }
+    }
+    return { contract };
+}
+function wrapResult(result, contract) {
+    if (result.error) {
+        return toCallToolResult({
+            error: true,
+            code: result.code,
+            message: result.message ?? "Backend call failed",
+        }, true);
+    }
+    if (contract) {
+        const envelope = annotateWithProvenance(result, contract.toolName, contract.contractVersion);
+        return toCallToolResult(envelope);
+    }
+    return toCallToolResult(result);
+}
+// ── Backend proxy methods ────────────────────────────────────────────────
+/**
+ * POSTs to a NestPilot backend endpoint and returns a CallToolResult.
+ * For plan endpoints (/api/plan/*), normalizes enum type fields to lowercase.
+ */
+export async function proxyPostTool(endpoint, args, opts = {}) {
+    const { contract, denied } = runPipeline(opts);
+    if (denied)
+        return denied;
+    const payload = endpoint.startsWith("/api/plan")
+        ? normalizePlanPayload(args)
+        : args;
+    const result = await nestpilotClient.post(endpoint, payload, {
+        headers: buildAuthHeaders(opts.authCtx),
+    });
+    return wrapResult(result, contract);
+}
+/**
+ * GETs from a NestPilot backend endpoint and returns a CallToolResult.
+ */
+export async function proxyGetTool(endpoint, params, opts = {}) {
+    const { contract, denied } = runPipeline(opts);
+    if (denied)
+        return denied;
+    const result = await nestpilotClient.get(endpoint, params, {
+        headers: buildAuthHeaders(opts.authCtx),
+    });
+    return wrapResult(result, contract);
+}
+/**
+ * PUTs to a NestPilot backend endpoint and returns a CallToolResult.
+ * For plan endpoints (/api/plan/*), normalizes enum type fields to lowercase.
+ */
+export async function proxyPutTool(endpoint, args, opts = {}) {
+    const { contract, denied } = runPipeline(opts);
+    if (denied)
+        return denied;
+    const payload = endpoint.startsWith("/api/plan")
+        ? normalizePlanPayload(args)
+        : args;
+    const result = await nestpilotClient.put(endpoint, payload, {
+        headers: buildAuthHeaders(opts.authCtx),
+    });
+    return wrapResult(result, contract);
+}
+/**
+ * DELETEs from a NestPilot backend endpoint and returns a CallToolResult.
+ */
+export async function proxyDeleteTool(endpoint, opts = {}) {
+    const { contract, denied } = runPipeline(opts);
+    if (denied)
+        return denied;
+    const result = await nestpilotClient.del(endpoint, {
+        headers: buildAuthHeaders(opts.authCtx),
+    });
+    return wrapResult(result, contract);
+}
+/**
+ * PATCHes to a NestPilot backend endpoint and returns a CallToolResult.
+ */
+export async function proxyPatchTool(endpoint, args, opts = {}) {
+    const { contract, denied } = runPipeline(opts);
+    if (denied)
+        return denied;
+    const result = await nestpilotClient.patch(endpoint, args, {
+        headers: buildAuthHeaders(opts.authCtx),
+    });
+    return wrapResult(result, contract);
+}

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