@nestpilot/mcp-app 1.0.0

package/dist/skills/tools/verify_forecast.md

@@ -0,0 +1,43 @@
+# Tool Skill: verify_forecast
+
+Runs a retirement forecast 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.
+
+## When to Use
+
+Use `verify_forecast` when the user wants to:
+- Verify numbers from their financial advisor
+- Create an auditable record of their retirement projection
+- Get a "second opinion" on a specific set of assumptions
+
+## Core Purpose: Independent Verification
+
+This is NestPilot's signature capability. The verification packet is the user's proof that
+the math was run independently, with explicit assumptions, and the results are reproducible.
+
+ALWAYS frame verification as: "Let's verify these numbers independently."
+NEVER suggest the advisor was wrong — present the verification as a confirmation or a
+starting point for a conversation with the advisor.
+
+## Presenting the Verification Packet
+
+Structure the response in three parts:
+1. **Assumptions verified**: List the key inputs (return rate, withdrawal rate, balance,
+   timeline) that were used in the calculation.
+2. **Result**: The verified balance, income, and longevity assessment.
+3. **Verdict**: "The projection is mathematically consistent with the stated assumptions" OR
+   "The projection assumes [X] which appears [optimistic/conservative] — here's why..."
+
+## Framing the Verdict
+
+- If results match: "The projection checks out. The math supports a balance of $[X] at age [Y]
+  under these assumptions."
+- If there's a discrepancy: "Our calculation shows $[X] vs the stated $[Y]. The difference is
+  likely due to [possible cause]. We recommend confirming the assumed return rate and
+  whether Social Security income is included."
+- NEVER say "your advisor is wrong" — say "the numbers differ, which is worth discussing."
+
+## Error Handling
+
+Same as `run_forecast`. Validation errors should prompt clarification of the specific field.

package/dist/src/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Unified MCP App configuration.
+ *
+ * Merges the original mcp-app config with mcp-edge production features:
+ * authentication, rate limiting, telemetry.
+ */
+export interface AppConfig {
+    port: number;
+    backendUrl: string;
+    agentRuntimeUrl: string;
+    /** "token" = opaque token validation (existing), "jwt-passthrough" = forward JWT to backend */
+    authMode: "token" | "jwt-passthrough";
+    requireAuth: boolean;
+    authTokens: Set<string>;
+    defaultUserId: string;
+    rateLimitWindowMs: number;
+    rateLimitMaxRequests: number;
+    enableConsoleTracing: boolean;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;

package/dist/src/config.js

@@ -0,0 +1,44 @@
+/**
+ * Unified MCP App configuration.
+ *
+ * Merges the original mcp-app config with mcp-edge production features:
+ * authentication, rate limiting, telemetry.
+ */
+function parseBoolean(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    return fallback;
+}
+function parsePositiveInt(value, fallback) {
+    if (!value)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) || parsed <= 0 ? fallback : parsed;
+}
+function parseTokenSet(value) {
+    if (!value)
+        return new Set();
+    return new Set(value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean));
+}
+export function loadConfig(env = process.env) {
+    return {
+        port: parsePositiveInt(env.PORT, 3001),
+        backendUrl: env.NESTPILOT_BACKEND_URL ?? "http://localhost:8080",
+        agentRuntimeUrl: env.AGENT_RUNTIME_URL ?? "http://localhost:3002",
+        authMode: env.MCP_AUTH_MODE === "jwt-passthrough" ? "jwt-passthrough" : "token",
+        requireAuth: parseBoolean(env.MCP_REQUIRE_AUTH, true),
+        authTokens: parseTokenSet(env.MCP_AUTH_TOKENS),
+        defaultUserId: env.MCP_DEFAULT_USER_ID ?? "anonymous",
+        rateLimitWindowMs: parsePositiveInt(env.MCP_RATE_LIMIT_WINDOW_MS, 60_000),
+        rateLimitMaxRequests: parsePositiveInt(env.MCP_RATE_LIMIT_MAX_REQUESTS, 60),
+        enableConsoleTracing: parseBoolean(env.MCP_ENABLE_CONSOLE_TRACING, false),
+    };
+}

package/dist/src/contracts/provenance.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Provenance Annotator — FEAT-0056
+ *
+ * Appends source, timestamp, and contract metadata to successful
+ * tool responses. Every tool result envelope includes provenance
+ * fields so decisions are traceable and auditable.
+ *
+ * @feature FEAT-0056
+ */
+export interface ProvenanceMetadata {
+    source: string;
+    timestamp: string;
+    contractVersion: string;
+    requestId: string;
+    toolName: string;
+}
+export interface ProvenanceEnvelope<T = unknown> {
+    data: T;
+    provenance: ProvenanceMetadata;
+}
+/**
+ * Wraps a tool result payload with provenance metadata.
+ */
+export declare function annotateWithProvenance<T>(data: T, toolName: string, contractVersion: string): ProvenanceEnvelope<T>;
+/**
+ * Checks whether a payload already has a provenance envelope.
+ */
+export declare function hasProvenance(payload: unknown): payload is ProvenanceEnvelope;
+/**
+ * Validates that a provenance envelope has all required fields.
+ * Returns an array of missing field names (empty = valid).
+ */
+export declare function validateProvenance(envelope: ProvenanceEnvelope): string[];
+/**
+ * Resets the request counter (for testing only).
+ */
+export declare function _resetRequestCounter(): void;

package/dist/src/contracts/provenance.js

@@ -0,0 +1,71 @@
+/**
+ * Provenance Annotator — FEAT-0056
+ *
+ * Appends source, timestamp, and contract metadata to successful
+ * tool responses. Every tool result envelope includes provenance
+ * fields so decisions are traceable and auditable.
+ *
+ * @feature FEAT-0056
+ */
+// ── Constants ────────────────────────────────────────────────────────────
+const SOURCE = "nestpilot-mcp-app";
+let requestCounter = 0;
+function generateRequestId() {
+    requestCounter += 1;
+    return `req-${Date.now()}-${requestCounter}`;
+}
+// ── Annotator ────────────────────────────────────────────────────────────
+/**
+ * Wraps a tool result payload with provenance metadata.
+ */
+export function annotateWithProvenance(data, toolName, contractVersion) {
+    return {
+        data,
+        provenance: {
+            source: SOURCE,
+            timestamp: new Date().toISOString(),
+            contractVersion,
+            requestId: generateRequestId(),
+            toolName,
+        },
+    };
+}
+/**
+ * Checks whether a payload already has a provenance envelope.
+ */
+export function hasProvenance(payload) {
+    if (payload && typeof payload === "object" && "provenance" in payload) {
+        const p = payload.provenance;
+        return (typeof p === "object" &&
+            p !== null &&
+            typeof p.source === "string" &&
+            typeof p.timestamp === "string" &&
+            typeof p.contractVersion === "string");
+    }
+    return false;
+}
+/**
+ * Validates that a provenance envelope has all required fields.
+ * Returns an array of missing field names (empty = valid).
+ */
+export function validateProvenance(envelope) {
+    const missing = [];
+    const p = envelope.provenance;
+    if (!p.source)
+        missing.push("source");
+    if (!p.timestamp)
+        missing.push("timestamp");
+    if (!p.contractVersion)
+        missing.push("contractVersion");
+    if (!p.requestId)
+        missing.push("requestId");
+    if (!p.toolName)
+        missing.push("toolName");
+    return missing;
+}
+/**
+ * Resets the request counter (for testing only).
+ */
+export function _resetRequestCounter() {
+    requestCounter = 0;
+}

package/dist/src/contracts/tool-contract-registry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tool Contract Registry — FEAT-0056
+ *
+ * Stores versioned contract descriptors for P0 retirement MCP tools.
+ * Each descriptor defines the tool's interface contract including schema
+ * references, idempotency mode, and error semantics.
+ *
+ * @feature FEAT-0056
+ */
+export type IdempotencyMode = "none" | "idempotent" | "safe-retry";
+export interface ToolContractDescriptor {
+    toolName: string;
+    contractVersion: string;
+    inputSchemaRef: string;
+    outputSchemaRef: string;
+    errorSchemaRef: string;
+    idempotencyMode: IdempotencyMode;
+    privileged: boolean;
+    description: string;
+}
+export interface ContractLookupResult {
+    found: true;
+    contract: ToolContractDescriptor;
+}
+export interface ContractLookupMiss {
+    found: false;
+    toolName: string;
+    reason: string;
+}
+export type ContractLookup = ContractLookupResult | ContractLookupMiss;
+/**
+ * Look up the contract descriptor for a given tool name.
+ */
+export declare function lookupContract(toolName: string): ContractLookup;
+/**
+ * Returns all registered contract descriptors.
+ */
+export declare function getAllContracts(): ReadonlyArray<ToolContractDescriptor>;
+/**
+ * Validates that a tool name has a registered contract.
+ * Returns the contract version on success, or throws on failure.
+ */
+export declare function requireContract(toolName: string): ToolContractDescriptor;

package/dist/src/contracts/tool-contract-registry.js

@@ -0,0 +1,282 @@
+/**
+ * Tool Contract Registry — FEAT-0056
+ *
+ * Stores versioned contract descriptors for P0 retirement MCP tools.
+ * Each descriptor defines the tool's interface contract including schema
+ * references, idempotency mode, and error semantics.
+ *
+ * @feature FEAT-0056
+ */
+// ── P0 Retirement Tool Contracts ─────────────────────────────────────────
+const P0_CONTRACTS = [
+    {
+        toolName: "create_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-schema-v1.json#/quickstart",
+        outputSchemaRef: "schemas/plan-schema-v1.json#/projection",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Quick retirement projection from basic inputs",
+    },
+    {
+        toolName: "run_forecast",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-schema-v1.json#/extended",
+        outputSchemaRef: "schemas/forecast-schema-v1.json",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Comprehensive multi-account retirement forecast",
+    },
+    {
+        toolName: "run_scenario",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-schema-v1.json#/scenario",
+        outputSchemaRef: "schemas/forecast-schema-v1.json#/scenario-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "What-if scenario comparison with deltas and stress tests",
+    },
+    {
+        toolName: "verify_forecast",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-schema-v1.json#/extended",
+        outputSchemaRef: "schemas/forecast-schema-v1.json#/verification-packet",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Auditable forecast verification with trace",
+    },
+    {
+        toolName: "coach",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/coach-schema-v1.1.json#/input",
+        outputSchemaRef: "schemas/coach-schema-v1.1.json#/output",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "AI-powered retirement coaching guidance",
+    },
+    {
+        toolName: "medicare-analyze",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/medicare-analyze-v1.json#/input",
+        outputSchemaRef: "schemas/medicare-analyze-v1.json#/output",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Medicare enrollment health check analysis",
+    },
+    {
+        toolName: "optimize_roth_conversion",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/roth-optimization-v1.json#/input",
+        outputSchemaRef: "schemas/roth-optimization-v1.json#/output",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Multi-year Roth conversion optimization with tax impact analysis",
+    },
+    // ── Plan management contracts ───────────────────────────────────────
+    {
+        toolName: "list_plans",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/list",
+        outputSchemaRef: "schemas/plan-management-v1.json#/list-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Lists all saved retirement plans for the authenticated user",
+    },
+    {
+        toolName: "get_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/get",
+        outputSchemaRef: "schemas/plan-management-v1.json#/get-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Retrieves a single saved plan by ID",
+    },
+    {
+        toolName: "get_active_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/get-active",
+        outputSchemaRef: "schemas/plan-management-v1.json#/get-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Retrieves the user's currently active plan",
+    },
+    {
+        toolName: "create_saved_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/create",
+        outputSchemaRef: "schemas/plan-management-v1.json#/create-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "none",
+        privileged: false,
+        description: "Creates and persists a new retirement plan",
+    },
+    {
+        toolName: "save_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/save",
+        outputSchemaRef: "schemas/plan-management-v1.json#/save-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Updates an existing saved plan with new inputs",
+    },
+    {
+        toolName: "activate_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/activate",
+        outputSchemaRef: "schemas/plan-management-v1.json#/activate-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Sets a plan as the user's active default plan",
+    },
+    {
+        toolName: "delete_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/delete",
+        outputSchemaRef: "schemas/plan-management-v1.json#/delete-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "none",
+        privileged: false,
+        description: "Soft-deletes a saved plan",
+    },
+    {
+        toolName: "rename_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/rename",
+        outputSchemaRef: "schemas/plan-management-v1.json#/rename-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Renames an existing plan",
+    },
+    {
+        toolName: "get_plan_components",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-management-v1.json#/components",
+        outputSchemaRef: "schemas/plan-management-v1.json#/components-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Retrieves financial components attached to a saved plan",
+    },
+    // ── Forecast management contracts ───────────────────────────────────
+    {
+        toolName: "run_saved_forecast",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/forecast-management-v1.json#/run",
+        outputSchemaRef: "schemas/forecast-management-v1.json#/run-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "none",
+        privileged: false,
+        description: "Triggers a forecast run for a saved plan",
+    },
+    {
+        toolName: "get_baseline_forecast",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/forecast-management-v1.json#/get-baseline",
+        outputSchemaRef: "schemas/forecast-management-v1.json#/get-baseline-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Retrieves the most recent baseline forecast for a saved plan",
+    },
+    // ── Scenario management contracts ───────────────────────────────────
+    {
+        toolName: "save_scenario",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/scenario-management-v1.json#/save",
+        outputSchemaRef: "schemas/scenario-management-v1.json#/save-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "none",
+        privileged: false,
+        description: "Persists a what-if scenario",
+    },
+    {
+        toolName: "list_scenarios",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/scenario-management-v1.json#/list",
+        outputSchemaRef: "schemas/scenario-management-v1.json#/list-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Lists saved scenarios, optionally filtered by plan",
+    },
+    {
+        toolName: "get_scenario",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/scenario-management-v1.json#/get",
+        outputSchemaRef: "schemas/scenario-management-v1.json#/get-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "safe-retry",
+        privileged: false,
+        description: "Retrieves a single saved scenario by ID",
+    },
+    {
+        toolName: "delete_scenario",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/scenario-management-v1.json#/delete",
+        outputSchemaRef: "schemas/scenario-management-v1.json#/delete-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "none",
+        privileged: false,
+        description: "Deletes a saved scenario by ID",
+    },
+    // ── Comprehensive plan contract ─────────────────────────────────────
+    {
+        toolName: "comprehensive_plan",
+        contractVersion: "1.0.0",
+        inputSchemaRef: "schemas/plan-schema-v1.json#/extended",
+        outputSchemaRef: "schemas/plan-schema-v1.json#/comprehensive-result",
+        errorSchemaRef: "schemas/error-envelope-v1.json",
+        idempotencyMode: "idempotent",
+        privileged: false,
+        description: "Combined coach insights + forecast in a single call",
+    },
+];
+// ── Registry ─────────────────────────────────────────────────────────────
+const contractMap = new Map();
+for (const contract of P0_CONTRACTS) {
+    contractMap.set(contract.toolName, contract);
+}
+/**
+ * Look up the contract descriptor for a given tool name.
+ */
+export function lookupContract(toolName) {
+    const contract = contractMap.get(toolName);
+    if (contract) {
+        return { found: true, contract };
+    }
+    return {
+        found: false,
+        toolName,
+        reason: `No contract registered for tool '${toolName}'`,
+    };
+}
+/**
+ * Returns all registered contract descriptors.
+ */
+export function getAllContracts() {
+    return P0_CONTRACTS;
+}
+/**
+ * Validates that a tool name has a registered contract.
+ * Returns the contract version on success, or throws on failure.
+ */
+export function requireContract(toolName) {
+    const lookup = lookupContract(toolName);
+    if (!lookup.found) {
+        throw new Error(`Contract validation failed: ${lookup.reason}`);
+    }
+    return lookup.contract;
+}

package/dist/src/local/cloud-compute-client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cloud Compute Client — sends PII-free mathematical payloads to the
+ * NestPilot cloud API for compute-intensive operations (forecast, scenario,
+ * Roth optimization, coaching).
+ *
+ * All requests include:
+ *  - `Authorization: Bearer {apiKey}` for metering
+ *  - `X-Client-Mode: local` to distinguish local-first traffic
+ *  - 30 second timeout
+ *
+ * On network failure, the client returns cached results when available.
+ *
+ * @feature FEAT-0087
+ */
+export interface CloudComputeResult {
+    data?: Record<string, unknown>;
+    error?: boolean;
+    message?: string;
+    cached?: boolean;
+}
+export declare class CloudComputeClient {
+    private cloudApiUrl;
+    private apiKey;
+    constructor(cloudApiUrl: string, apiKey: string);
+    /**
+     * Run a retirement forecast against the cloud engine.
+     */
+    forecast(payload: Record<string, unknown>): Promise<CloudComputeResult>;
+    /**
+     * Run a what-if scenario comparison against the cloud engine.
+     */
+    scenario(payload: Record<string, unknown>): Promise<CloudComputeResult>;
+    /**
+     * Run Roth conversion optimization against the cloud engine.
+     */
+    rothOptimize(payload: Record<string, unknown>): Promise<CloudComputeResult>;
+    /**
+     * Get AI coaching guidance from the cloud engine.
+     */
+    coach(payload: Record<string, unknown>): Promise<CloudComputeResult>;
+    /**
+     * Run forecast verification against the cloud engine.
+     */
+    verify(payload: Record<string, unknown>): Promise<CloudComputeResult>;
+    /**
+     * Quick-calc for initial plan creation.
+     */
+    quickCalc(payload: Record<string, unknown>): Promise<CloudComputeResult>;
+    /**
+     * Health check — verifies the cloud API is reachable.
+     */
+    healthCheck(): Promise<boolean>;
+    private post;
+    private buildHeaders;
+}