@savvly/mcp-server 1.0.0 → 1.0.2

package/dist/cli.js

@@ -3105,6 +3105,9 @@ var require_utils = __commonJS({
     "use strict";
     var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
     var isIPv4 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
+    var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
+    var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
+    var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
     function stringArrayToHexStripped(input) {
       let acc = "";
       let code = 0;
@@ -3297,27 +3300,77 @@ var require_utils = __commonJS({
       }
       return output.join("");
     }
-    function normalizeComponentEncoding(component, esc2) {
-      const func = esc2 !== true ? escape : unescape;
-      if (component.scheme !== void 0) {
-        component.scheme = func(component.scheme);
-      }
-      if (component.userinfo !== void 0) {
-        component.userinfo = func(component.userinfo);
-      }
-      if (component.host !== void 0) {
-        component.host = func(component.host);
+    var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
+    var HOST_DELIM_RE = /[@/?#:]/g;
+    var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
+    function reescapeHostDelimiters(host, isIP) {
+      const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+      re.lastIndex = 0;
+      return host.replace(re, (ch) => HOST_DELIMS[ch]);
+    }
+    function normalizePercentEncoding(input, decodeUnreserved = false) {
+      if (input.indexOf("%") === -1) {
+        return input;
       }
-      if (component.path !== void 0) {
-        component.path = func(component.path);
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex = input.slice(i + 1, i + 3);
+          if (isHexPair(hex)) {
+            const normalizedHex = hex.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decodeUnreserved && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        output += input[i];
       }
-      if (component.query !== void 0) {
-        component.query = func(component.query);
+      return output;
+    }
+    function normalizePathEncoding(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex = input.slice(i + 1, i + 3);
+          if (isHexPair(hex)) {
+            const normalizedHex = hex.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decoded !== "." && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        if (isPathCharacter(input[i])) {
+          output += input[i];
+        } else {
+          output += escape(input[i]);
+        }
       }
-      if (component.fragment !== void 0) {
-        component.fragment = func(component.fragment);
+      return output;
+    }
+    function escapePreservingEscapes(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex = input.slice(i + 1, i + 3);
+          if (isHexPair(hex)) {
+            output += "%" + hex.toUpperCase();
+            i += 2;
+            continue;
+          }
+        }
+        output += escape(input[i]);
       }
-      return component;
+      return output;
     }
     function recomposeAuthority(component) {
       const uriTokens = [];
@@ -3332,7 +3385,7 @@ var require_utils = __commonJS({
           if (ipV6res.isIPV6 === true) {
             host = `[${ipV6res.escapedHost}]`;
           } else {
-            host = component.host;
+            host = reescapeHostDelimiters(host, false);
           }
         }
         uriTokens.push(host);
@@ -3346,7 +3399,10 @@ var require_utils = __commonJS({
     module.exports = {
       nonSimpleDomain,
       recomposeAuthority,
-      normalizeComponentEncoding,
+      reescapeHostDelimiters,
+      normalizePercentEncoding,
+      normalizePathEncoding,
+      escapePreservingEscapes,
       removeDotSegments,
       isIPv4,
       isUUID,
@@ -3570,12 +3626,12 @@ var require_schemes = __commonJS({
 var require_fast_uri = __commonJS({
   "../../node_modules/fast-uri/index.js"(exports, module) {
     "use strict";
-    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizeComponentEncoding, isIPv4, nonSimpleDomain } = require_utils();
+    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
     function normalize(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
-        serialize(parse3(uri, options), options);
+        normalizeString(uri, options);
       } else if (typeof uri === "object") {
         uri = /** @type {T} */
         parse3(serialize(uri, options), options);
@@ -3642,19 +3698,9 @@ var require_fast_uri = __commonJS({
       return target;
     }
     function equal(uriA, uriB, options) {
-      if (typeof uriA === "string") {
-        uriA = unescape(uriA);
-        uriA = serialize(normalizeComponentEncoding(parse3(uriA, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriA === "object") {
-        uriA = serialize(normalizeComponentEncoding(uriA, true), { ...options, skipEscape: true });
-      }
-      if (typeof uriB === "string") {
-        uriB = unescape(uriB);
-        uriB = serialize(normalizeComponentEncoding(parse3(uriB, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriB === "object") {
-        uriB = serialize(normalizeComponentEncoding(uriB, true), { ...options, skipEscape: true });
-      }
-      return uriA.toLowerCase() === uriB.toLowerCase();
+      const normalizedA = normalizeComparableURI(uriA, options);
+      const normalizedB = normalizeComparableURI(uriB, options);
+      return normalizedA !== void 0 && normalizedB !== void 0 && normalizedA.toLowerCase() === normalizedB.toLowerCase();
     }
     function serialize(cmpts, opts) {
       const component = {
@@ -3679,12 +3725,12 @@ var require_fast_uri = __commonJS({
       if (schemeHandler && schemeHandler.serialize) schemeHandler.serialize(component, options);
       if (component.path !== void 0) {
         if (!options.skipEscape) {
-          component.path = escape(component.path);
+          component.path = escapePreservingEscapes(component.path);
           if (component.scheme !== void 0) {
             component.path = component.path.split("%3A").join(":");
           }
         } else {
-          component.path = unescape(component.path);
+          component.path = normalizePercentEncoding(component.path);
         }
       }
       if (options.reference !== "suffix" && component.scheme) {
@@ -3719,7 +3765,16 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
-    function parse3(uri, opts) {
+    function getParseError(parsed, matches) {
+      if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
+        return 'URI path must start with "/" when authority is present.';
+      }
+      if (typeof parsed.port === "number" && (parsed.port < 0 || parsed.port > 65535)) {
+        return "URI port is malformed.";
+      }
+      return void 0;
+    }
+    function parseWithStatus(uri, opts) {
       const options = Object.assign({}, opts);
       const parsed = {
         scheme: void 0,
@@ -3730,6 +3785,7 @@ var require_fast_uri = __commonJS({
         query: void 0,
         fragment: void 0
       };
+      let malformedAuthorityOrPort = false;
       let isIP = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
@@ -3750,6 +3806,11 @@ var require_fast_uri = __commonJS({
         if (isNaN(parsed.port)) {
           parsed.port = matches[5];
         }
+        const parseError = getParseError(parsed, matches);
+        if (parseError !== void 0) {
+          parsed.error = parsed.error || parseError;
+          malformedAuthorityOrPort = true;
+        }
         if (parsed.host) {
           const ipv4result = isIPv4(parsed.host);
           if (ipv4result === false) {
@@ -3788,14 +3849,18 @@ var require_fast_uri = __commonJS({
               parsed.scheme = unescape(parsed.scheme);
             }
             if (parsed.host !== void 0) {
-              parsed.host = unescape(parsed.host);
+              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
             }
           }
           if (parsed.path) {
-            parsed.path = escape(unescape(parsed.path));
+            parsed.path = normalizePathEncoding(parsed.path);
           }
           if (parsed.fragment) {
-            parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            try {
+              parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            } catch {
+              parsed.error = parsed.error || "URI malformed";
+            }
           }
         }
         if (schemeHandler && schemeHandler.parse) {
@@ -3804,7 +3869,29 @@ var require_fast_uri = __commonJS({
       } else {
         parsed.error = parsed.error || "URI can not be parsed.";
       }
-      return parsed;
+      return { parsed, malformedAuthorityOrPort };
+    }
+    function parse3(uri, opts) {
+      return parseWithStatus(uri, opts).parsed;
+    }
+    function normalizeString(uri, opts) {
+      return normalizeStringWithStatus(uri, opts).normalized;
+    }
+    function normalizeStringWithStatus(uri, opts) {
+      const { parsed, malformedAuthorityOrPort } = parseWithStatus(uri, opts);
+      return {
+        normalized: malformedAuthorityOrPort ? uri : serialize(parsed, opts),
+        malformedAuthorityOrPort
+      };
+    }
+    function normalizeComparableURI(uri, opts) {
+      if (typeof uri === "string") {
+        const { normalized, malformedAuthorityOrPort } = normalizeStringWithStatus(uri, opts);
+        return malformedAuthorityOrPort ? void 0 : normalized;
+      }
+      if (typeof uri === "object") {
+        return serialize(uri, opts);
+      }
     }
     var fastUri = {
       SCHEMES,
@@ -21616,6 +21703,9 @@ var PRODUCT_COMPARISON = {
 };
 var VALID_PRODUCT_TYPES = COMPARISONS.map((c) => c.product_type);
 
+// ../../src/mcp/version.ts
+var SERVER_VERSION = "1.0.2";
+
 // ../../src/data/faq.ts
 var FAQ = [
   {
@@ -22256,7 +22346,7 @@ var QA_LIBRARY = [
     "question": "What CTAs work for benefit brokers and employers?",
     "answer": "Book a Demo or Learn more at savvly.com. \u2014 Ready to offer a benefit that lasts a lifetime? Book a demo or explore our payout estimator online. \u2014 Three steps to launch: Book a discovery call, Design your plan, Go live in days. \u2014 Learn how Savvly can help your employees build a future grounded in confidence.",
     "footnotes": [
-      "Savvly's Longevity Benefit is structured as a pooled investment plan offered through the Savvly Fund, a registered closed-end fund under the Investment Company Act of 1940. It is not a guaranteed income product, not insurance, and not FDIC insured. Participation involves investment risk, including the possible loss of principal. Payouts are contingent on factors including market performance, mortality experience, and the timing of withdrawals. Savvly Advisor, LLC is a registered investment adviser. This material is for informational purposes only and does not constitute personalized investment advice. For complete information on risks, fees, structure, and eligibility, visit savvly.com/disclosure."
+      "Savvly's Longevity Benefit is structured as a pooled investment plan offered through the Savvly Fund, a registered closed-end fund under the Investment Company Act of 1940. It is not a guaranteed income product, not insurance, and not FDIC insured. Participation involves investment risk, including the possible loss of principal. Payouts are contingent on factors including market performance, mortality experience, and the timing of withdrawals. Savvly Advisor, LLC is a registered investment adviser. This material is for informational purposes only and does not constitute personalized investment advice. For complete information on risks, fees, structure, and eligibility, visit savvly.com/disclosures."
     ],
     "id": "universal/calls-to-action-by-audience/what-ctas-work-for-benefit-brokers-and-employers"
   }
@@ -22333,17 +22423,9 @@ var AdvisorClientError = class extends Error {
   status;
   responseBody;
 };
-var AdvisorNotConfigured = class extends Error {
-  constructor() {
-    super(
-      "advisor_functions URL is not configured. Set ADVISOR_FUNCTIONS_URL (e.g. https://advisor-functions.example.net/api) to enable projections."
-    );
-    this.name = "AdvisorNotConfigured";
-  }
-};
+var DEFAULT_ADVISOR_FUNCTIONS_URL = "https://savvly-estimator.azurewebsites.net";
 function getBaseUrl() {
-  const url = process.env.ADVISOR_FUNCTIONS_URL;
-  if (!url) throw new AdvisorNotConfigured();
+  const url = process.env.ADVISOR_FUNCTIONS_URL ?? DEFAULT_ADVISOR_FUNCTIONS_URL;
   const trimmed = url.replace(/\/+$/, "");
   return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
 }
@@ -22443,42 +22525,42 @@ var PayoutAgeRowSchema = external_exports.object({
     "Milestone age (in years) at which this payout row is reported. The estimator returns rows for ages 80, 85, 90, and 95 by default."
   ),
   savvly_payout_lower: external_exports.number().describe(
-    "USD. Lower bound of the modeled payout WITH Savvly at this milestone age."
+    "USD. Lower bound of the modeled payout with Savvly at this milestone age."
   ),
   savvly_payout_upper: external_exports.number().describe(
-    "USD. Upper bound (central illustrative estimate) of the payout WITH Savvly at this milestone age. Use this when surfacing a single number."
+    "USD. Upper bound (central illustrative estimate) of the payout with Savvly at this milestone age. Use this when surfacing a single number."
   ),
-  payout_without_savvly_lower: external_exports.number().describe(
-    "USD. Lower bound of the counterfactual payout WITHOUT Savvly (markets alone) at this age. May be 0 once the modeled market-only portfolio has been fully drawn down by withdrawals."
+  payout_market_alone_lower: external_exports.number().describe(
+    "USD. Lower bound of the counterfactual market alone payout at this age. May be 0 once the modeled market alone portfolio has been fully drawn down by withdrawals."
   ),
-  payout_without_savvly_upper: external_exports.number().describe(
-    "USD. Upper bound of the counterfactual payout WITHOUT Savvly at this age. May be 0 once the market-only portfolio has been depleted."
+  payout_market_alone_upper: external_exports.number().describe(
+    "USD. Upper bound of the counterfactual market alone payout at this age. May be 0 once the market alone portfolio has been depleted."
   ),
   savvly_upside_lower: external_exports.number().describe(
-    "USD. Lower bound for the incremental payout at this age attributable to Savvly's Longevity Benefit (savvly_payout \u2212 payout_without_savvly)."
+    "USD. Lower bound for the incremental payout at this age attributable to Savvly's Longevity Benefit (savvly_payout \u2212 payout_market_alone)."
   ),
   savvly_upside_upper: external_exports.number().describe(
-    "USD. Upper bound for the incremental Savvly-only upside at this age. Tends to be large at 90/95 where the market-only portfolio is depleted."
+    "USD. Upper bound for the incremental Savvly upside at this age. Tends to be large at 90/95 where the market alone portfolio is depleted."
   )
 });
 var PayoutEnvelopeSchema = external_exports.object({
   total_savvly_upside_lower: external_exports.number().describe(
-    "USD. Lower bound of the cumulative incremental upside Savvly provides vs. investing in markets alone, summed across all milestone payout ages."
+    "USD. Lower bound of the cumulative incremental upside Savvly provides vs. investing in the market alone, summed across all milestone payout ages."
   ),
   total_savvly_upside_upper: external_exports.number().describe(
-    "USD. Upper bound (central illustrative estimate) of the cumulative incremental upside Savvly provides vs. markets alone. Equals `total_savvly_upper \u2212 total_without_savvly_upper`."
+    "USD. Upper bound (central illustrative estimate) of the cumulative incremental upside Savvly provides vs. market alone. Equals `total_savvly_upper \u2212 total_market_alone_upper`."
   ),
   total_savvly_lower: external_exports.number().describe(
-    "USD. Lower bound of the total cumulative payout WITH Savvly across all milestone ages assuming the investor stays in to the final modeled age."
+    "USD. Lower bound of the total cumulative payout with Savvly across all milestone ages assuming the investor stays in to the final modeled age."
   ),
   total_savvly_upper: external_exports.number().describe(
-    "USD. Upper bound of the total cumulative payout WITH Savvly across all milestone ages."
+    "USD. Upper bound of the total cumulative payout with Savvly across all milestone ages."
   ),
-  total_without_savvly_lower: external_exports.number().describe(
-    "USD. Lower bound of the cumulative payout WITHOUT Savvly \u2014 the market-alone counterfactual."
+  total_market_alone_lower: external_exports.number().describe(
+    "USD. Lower bound of the cumulative counterfactual market alone payout."
   ),
-  total_without_savvly_upper: external_exports.number().describe(
-    "USD. Upper bound of the cumulative payout WITHOUT Savvly \u2014 the market-alone counterfactual."
+  total_market_alone_upper: external_exports.number().describe(
+    "USD. Upper bound of the cumulative counterfactual market alone payout."
   ),
   early_withdrawal_value: external_exports.number().describe(
     "USD. Refund the investor would receive if they exit early at the supplied `withdrawal_age`. Point estimate (no range). Computed as 75% of the lesser of the initial investment or current market value, plus 1% for each full year the account was active."
@@ -22496,7 +22578,7 @@ var PayoutEnvelopeSchema = external_exports.object({
     "Percent. Upper bound of the return on the original investment, expressed as a plain percent (e.g. 1710 = 1,710%)."
   ),
   payout_age_dependent_values: external_exports.array(PayoutAgeRowSchema).describe(
-    "Per-milestone-age breakdown of the projection. Typically 4 rows for ages 80, 85, 90, 95. Each row contains the WITH-Savvly payout, the WITHOUT-Savvly counterfactual, and the incremental Savvly upside for that age, each with `_lower`/`_upper` bounds."
+    "Per-milestone-age breakdown of the projection. Typically 4 rows for ages 80, 85, 90, 95. Each row contains the with Savvly payout, the market alone counterfactual, and the incremental Savvly upside for that age, each with `_lower`/`_upper` bounds."
   )
 });
 var RetirementAgeRowSchema = external_exports.object({
@@ -22529,6 +22611,17 @@ var RetirementEnvelopeSchema = external_exports.object({
     "Per-age timeline across the planning horizon (current_age \u2192 life_expectancy). One row per year."
   )
 });
+var TopLevelDisclosureSchema = external_exports.object({
+  required: external_exports.literal(true).describe(
+    "Always true. Signals to the calling AI client that the `text` and `url` fields MUST be displayed to the end user whenever any number from this response is shown. Required by SEC Marketing Rule and FINRA Rule 2210."
+  ),
+  text: external_exports.string().describe(
+    "Short verbatim SEC disclosure text. Display this string to the user alongside any projection figures from this response. Do not paraphrase, summarize, or omit."
+  ),
+  url: external_exports.string().describe(
+    "Canonical full-disclosures URL. Render as a clickable link to the user alongside the `text`. Required by SEC Marketing Rule and FINRA Rule 2210."
+  )
+});
 var DisclaimerMetadataSchema = external_exports.object({
   summary: external_exports.string().describe(
     "Short illustrative-purposes disclaimer matching the text directly below the chart on estimator.savvly.com. Surface this whenever you summarize the projection to a user."
@@ -22554,14 +22647,14 @@ var ProjectionSummarySchema = external_exports.object({
     "USD. Total amount deposited into Savvly. For single deposits this equals `funding_amount`. For monthly installments it equals `monthly_installment * installment_years * 12`."
   ),
   total_savvly_upper_usd: external_exports.number().nullable().describe("Convenience copy of `result.total_savvly_upper`."),
-  total_without_savvly_upper_usd: external_exports.number().nullable().describe("Convenience copy of `result.total_without_savvly_upper`."),
+  total_market_alone_upper_usd: external_exports.number().nullable().describe("Convenience copy of `result.total_market_alone_upper`."),
   savvly_above_market_upper_usd: external_exports.number().nullable().describe(
-    "USD. `total_savvly_upper \u2212 total_without_savvly_upper` (the central incremental upside). May differ slightly from `result.total_savvly_upside_upper` due to rounding."
+    "USD. `total_savvly_upper \u2212 total_market_alone_upper` (the central incremental upside). May differ slightly from `result.total_savvly_upside_upper` due to rounding."
   ),
   early_exit_refund_usd: external_exports.number().nullable().describe("Convenience copy of `result.early_withdrawal_value`."),
   percentage_gain_upper_percent: external_exports.number().nullable().describe("Convenience copy of `result.percentage_gain_upper`."),
   narrative: external_exports.string().describe(
-    "Human-readable English sentence summarizing the projection. Always ends with the phrase 'Payouts are illustrations, not guarantees.'"
+    "Human-readable English sentence summarizing the projection. Always ends with 'Payouts are not guarantees. See full disclosures at <url>.' \u2014 display the URL verbatim alongside any figures."
   )
 });
 var ProjectionResponseSchema = external_exports.object({
@@ -22572,6 +22665,9 @@ var ProjectionResponseSchema = external_exports.object({
   summary: ProjectionSummarySchema.describe(
     "Convenience summary including a human-readable narrative."
   ),
+  disclosure: TopLevelDisclosureSchema.describe(
+    "DISCLOSURE REQUIRED: display `disclosure.text` and link `disclosure.url` to the user whenever you present any number from this response. Required by SEC Marketing Rule and FINRA Rule 2210. The richer block under `metadata.disclaimer` is supplementary detail; this top-level field is the must-display."
+  ),
   metadata: external_exports.object({
     disclaimer: DisclaimerMetadataSchema,
     field_descriptions: external_exports.record(external_exports.string()).describe(
@@ -22579,21 +22675,58 @@ var ProjectionResponseSchema = external_exports.object({
     )
   })
 });
+var DisplayHintsSchema = external_exports.object({
+  chart: external_exports.object({
+    type: external_exports.literal("area"),
+    reference: external_exports.string(),
+    x_axis: external_exports.object({ field: external_exports.string(), label: external_exports.string() }),
+    y_axis: external_exports.object({ label: external_exports.string(), format: external_exports.string() }),
+    series: external_exports.array(
+      external_exports.object({
+        field: external_exports.string(),
+        label: external_exports.string(),
+        color: external_exports.string(),
+        fill: external_exports.string()
+      })
+    ),
+    interpolation: external_exports.literal("linear"),
+    show_markers: external_exports.boolean(),
+    tooltip: external_exports.record(external_exports.string())
+  }),
+  layout: external_exports.object({
+    above_chart: external_exports.string(),
+    below_chart: external_exports.string()
+  }),
+  rendering_notes: external_exports.array(external_exports.string())
+}).describe(
+  "Rendering guidance for the retirement projection chart. Tells AI clients to render `age_dependent_values` as a stacked area chart matching estimator.savvly.com \u2014 linear interpolation (no spline), no markers, so Savvly milestone payouts at ages 80/85/90/95 appear as sharp spikes with visible year-by-year depletion between them. KPI cards above and a narrative paragraph below the chart are encouraged."
+);
 var RetirementResponseSchema = external_exports.object({
   inputs: external_exports.record(external_exports.unknown()),
   result: RetirementEnvelopeSchema,
+  summary: external_exports.object({
+    narrative: external_exports.string().describe(
+      "Human-readable English sentence. Always ends with the canonical full-disclosures URL so AI clients that paraphrase past `metadata.disclaimer` still echo the disclosure link."
+    )
+  }).describe(
+    "Convenience summary. The narrative carries the canonical full-disclosures URL inline; display it verbatim alongside any figures from this response."
+  ),
+  disclosure: TopLevelDisclosureSchema.describe(
+    "DISCLOSURE REQUIRED: display `disclosure.text` and link `disclosure.url` to the user whenever you present any number from this response. Required by SEC Marketing Rule and FINRA Rule 2210."
+  ),
   metadata: external_exports.object({
     disclaimer: DisclaimerMetadataSchema,
-    field_descriptions: external_exports.record(external_exports.string())
+    field_descriptions: external_exports.record(external_exports.string()),
+    display_hints: DisplayHintsSchema
   })
 });
 var PAYOUT_FIELD_DESCRIPTIONS = {
-  total_savvly_upside_lower: "USD. Lower bound of cumulative Savvly-only upside vs market alone.",
-  total_savvly_upside_upper: "USD. Upper bound (central illustrative) of cumulative Savvly-only upside vs market alone.",
-  total_savvly_lower: "USD. Lower bound of total cumulative payout WITH Savvly through final age.",
-  total_savvly_upper: "USD. Upper bound of total cumulative payout WITH Savvly through final age.",
-  total_without_savvly_lower: "USD. Lower bound of cumulative counterfactual WITHOUT Savvly.",
-  total_without_savvly_upper: "USD. Upper bound of cumulative counterfactual WITHOUT Savvly.",
+  total_savvly_upside_lower: "USD. Lower bound of cumulative Savvly upside vs market alone.",
+  total_savvly_upside_upper: "USD. Upper bound (central illustrative) of cumulative Savvly upside vs market alone.",
+  total_savvly_lower: "USD. Lower bound of total cumulative payout with Savvly through final age.",
+  total_savvly_upper: "USD. Upper bound of total cumulative payout with Savvly through final age.",
+  total_market_alone_lower: "USD. Lower bound of cumulative market alone counterfactual.",
+  total_market_alone_upper: "USD. Upper bound of cumulative market alone counterfactual.",
   early_withdrawal_value: "USD. Refund if investor exits at `withdrawal_age`. Point estimate (no range).",
   total_payout_at_withdrawal_age_lower: "USD. Lower bound of total payout if exiting at `withdrawal_age`.",
   total_payout_at_withdrawal_age_upper: "USD. Upper bound of total payout if exiting at `withdrawal_age`.",
@@ -22601,12 +22734,12 @@ var PAYOUT_FIELD_DESCRIPTIONS = {
   percentage_gain_upper: "Percent. Upper bound of return on original investment.",
   payout_age_dependent_values: "Array. Per-milestone-age breakdown (ages 80/85/90/95). See payout_age_dependent_values[] field descriptions.",
   "payout_age_dependent_values[].payout_age": "Years. Milestone age this row reports.",
-  "payout_age_dependent_values[].savvly_payout_lower": "USD. Lower bound payout WITH Savvly at this age.",
-  "payout_age_dependent_values[].savvly_payout_upper": "USD. Upper bound payout WITH Savvly at this age.",
-  "payout_age_dependent_values[].payout_without_savvly_lower": "USD. Lower bound counterfactual WITHOUT Savvly. May be 0 once market-only portfolio is depleted.",
-  "payout_age_dependent_values[].payout_without_savvly_upper": "USD. Upper bound counterfactual WITHOUT Savvly at this age.",
-  "payout_age_dependent_values[].savvly_upside_lower": "USD. Lower bound for Savvly-only incremental upside at this age.",
-  "payout_age_dependent_values[].savvly_upside_upper": "USD. Upper bound for Savvly-only incremental upside at this age."
+  "payout_age_dependent_values[].savvly_payout_lower": "USD. Lower bound payout with Savvly at this age.",
+  "payout_age_dependent_values[].savvly_payout_upper": "USD. Upper bound payout with Savvly at this age.",
+  "payout_age_dependent_values[].payout_market_alone_lower": "USD. Lower bound market alone counterfactual. May be 0 once market alone portfolio is depleted.",
+  "payout_age_dependent_values[].payout_market_alone_upper": "USD. Upper bound market alone counterfactual at this age.",
+  "payout_age_dependent_values[].savvly_upside_lower": "USD. Lower bound for the Savvly incremental upside at this age.",
+  "payout_age_dependent_values[].savvly_upside_upper": "USD. Upper bound for the Savvly incremental upside at this age."
 };
 var RETIREMENT_FIELD_DESCRIPTIONS = {
   gap_score: "Server-computed score summarizing the savings-vs-paycheck gap.",
@@ -22719,19 +22852,28 @@ function disclaimerBlock() {
     full_disclosures_url: PRODUCT.disclaimers.full_disclosures_url
   };
 }
+function disclosureBlock() {
+  return {
+    required: true,
+    text: PRODUCT.disclaimers.projections,
+    url: PRODUCT.disclaimers.full_disclosures_url
+  };
+}
+var DISCLOSURE_REQUIRED_TERSE = "DISCLOSURE REQUIRED: display `disclosure.text` verbatim and link `disclosure.url` to the user alongside any figures from this response. Required by SEC Marketing Rule and FINRA Rule 2210 \u2014 do not paraphrase or omit.";
+var SAVVLY_VS_MARKET_ALONE_PAYOUT_METHODOLOGY = "Payout methodology \u2014 Savvly vs market alone: the payout values are calculated by comparing two investors of the same age committing the same principal. Investor 1 invests in the market with Savvly's Longevity Benefit Fund; Investor 2 invests in the market alone (no longevity overlay). To make the comparison apples-to-apples, at each milestone age (80, 85, 90, 95) Investor 2 withdraws from their market alone portfolio the same dollar amount Investor 1 receives as a payout from Savvly. The `payout_market_alone_*` and `total_market_alone_*` figures are therefore what Investor 2 can actually withdraw to match Savvly's payouts before running out \u2014 they fall to 0 once the market alone portfolio is depleted. The `savvly_upside_*` (and `total_savvly_upside_*`) fields quantify how much more total money Investor 1 receives in payouts from Savvly than Investor 2 is able to withdraw over time to match those payouts.";
 function summarizePayouts(envelope, depositType, deposited) {
   const totalSavvly = envelope.total_savvly_upper ?? null;
-  const totalMarket = envelope.total_without_savvly_upper ?? null;
+  const totalMarket = envelope.total_market_alone_upper ?? null;
   const upside = totalSavvly !== null && totalMarket !== null ? totalSavvly - totalMarket : null;
   const refund = envelope.early_withdrawal_value ?? null;
   const pctGain = envelope.percentage_gain_upper ?? null;
   const depositText = depositType === "single" ? `a single upfront deposit of ${formatUsd(deposited)}` : `monthly deposits totaling ${formatUsd(deposited)}`;
-  const narrative = `With ${depositText}, the Savvly Longevity Benefit could pay out roughly ${formatUsd(totalSavvly)} cumulatively through age 95 \u2014 ${formatUsd(upside)} more than investing in the markets alone (${formatUsd(totalMarket)}). ` + (refund !== null ? `If the investor exits early at the chosen withdrawal age, they would get back about ${formatUsd(refund)}. ` : "") + (pctGain !== null ? `That's an illustrative ${pctGain}% return on the original investment. ` : "") + "All Savvly figures are illustrative and presented net of Savvly's management fees (55 bps on purchased shares, 110 bps on allocated shares; typically blended in the 55-70 bps range). Payouts are not guarantees.";
+  const narrative = `With ${depositText}, the Savvly Longevity Benefit could pay out roughly ${formatUsd(totalSavvly)} cumulatively through age 95 \u2014 ${formatUsd(upside)} more than investing in the market alone (${formatUsd(totalMarket)}). ` + (refund !== null ? `If the investor exits early at the chosen withdrawal age, they would get back about ${formatUsd(refund)}. ` : "") + (pctGain !== null ? `That's an illustrative ${pctGain}% return on the original investment. ` : "") + `All Savvly figures are illustrative and presented net of Savvly's management fees (55 bps on purchased shares, 110 bps on allocated shares; typically blended in the 55-70 bps range). Payouts are not guarantees. See full disclosures at ${PRODUCT.disclaimers.full_disclosures_url}.`;
   return {
     deposit_type: depositType,
     deposited_amount_usd: deposited,
     total_savvly_upper_usd: totalSavvly,
-    total_without_savvly_upper_usd: totalMarket,
+    total_market_alone_upper_usd: totalMarket,
     savvly_above_market_upper_usd: upside,
     early_exit_refund_usd: refund,
     percentage_gain_upper_percent: pctGain,
@@ -22743,19 +22885,67 @@ function payoutPayload(inputs, result, depositType, deposited) {
     inputs,
     result,
     summary: summarizePayouts(result, depositType, deposited),
+    disclosure: disclosureBlock(),
     metadata: {
       disclaimer: disclaimerBlock(),
+      methodology: SAVVLY_VS_MARKET_ALONE_PAYOUT_METHODOLOGY,
       field_descriptions: PAYOUT_FIELD_DESCRIPTIONS
     }
   };
 }
+var RETIREMENT_DISPLAY_HINTS = {
+  chart: {
+    type: "area",
+    reference: "https://estimator.savvly.com \u2014 Retirement Forecast chart",
+    x_axis: { field: "age", label: "Age" },
+    y_axis: { label: "Balance (USD)", format: "currency_usd" },
+    series: [
+      {
+        field: "retirement_savings_without_savvly_in_the_portfolio",
+        label: "Current Retirement Forecast",
+        color: "#9CA3AF",
+        fill: "solid"
+      },
+      {
+        field: "retirement_savings_with_savvly_in_the_portfolio",
+        label: "With a longevity solution in the portfolio",
+        color: "#3B82F6",
+        fill: "solid"
+      }
+    ],
+    interpolation: "linear",
+    show_markers: false,
+    tooltip: {
+      age: "Age",
+      retirement_savings_without_savvly_in_the_portfolio: "Current Retirement Forecast",
+      retirement_savings_with_savvly_in_the_portfolio: "With a longevity solution in the portfolio",
+      difference_between_retirement_savings_with_and_without_savvly_in_the_portfolio: "Difference"
+    }
+  },
+  layout: {
+    above_chart: "kpi_cards",
+    below_chart: "narrative"
+  },
+  rendering_notes: [
+    "Plot `age_dependent_values` rows exactly as returned \u2014 one row per year. Savvly milestone payouts at ages 80/85/90/95 must appear as sharp vertical spikes on the with-Savvly series; year-by-year monthly-paycheck withdrawals show as the depletion between spikes. Do NOT smooth/spline the line \u2014 smoothing rounds the spikes off into bumps and misrepresents the payout schedule.",
+    "Render the without-Savvly series exactly as returned. It drops to 0 once the traditional portfolio is exhausted; do not extrapolate past that.",
+    "If `monthly_paycheck` was omitted (default 0), neither series will deplete and the chart is a pure accumulation curve \u2014 surface that caveat to the user."
+  ]
+};
+function disclosureNarrative(kind) {
+  const lead = kind === "retirement" ? "Hypothetical retirement projection \u2014 projections are based on assumed rates of return and are not guarantees of future performance." : "Hypothetical illustration of Savvly Longevity Benefit growth across the payout ages \u2014 not a guarantee of future performance.";
+  return `${lead} See full disclosures at ${PRODUCT.disclaimers.full_disclosures_url}.`;
+}
 function retirementPayload(inputs, result) {
   return {
     inputs,
     result,
+    summary: { narrative: disclosureNarrative("retirement") },
+    disclosure: disclosureBlock(),
     metadata: {
       disclaimer: disclaimerBlock(),
-      field_descriptions: RETIREMENT_FIELD_DESCRIPTIONS
+      field_descriptions: RETIREMENT_FIELD_DESCRIPTIONS,
+      display_hints: RETIREMENT_DISPLAY_HINTS
     }
   };
 }
@@ -22913,7 +23103,7 @@ function searchQaLibrary(opts) {
 function createMcpServer() {
   const server = new McpServer({
     name: "savvly",
-    version: "1.0.0"
+    version: SERVER_VERSION
   });
   server.resource(
     "product-overview",
@@ -23026,7 +23216,7 @@ function createMcpServer() {
     "project_savvly_lumpsum",
     {
       title: "Project Savvly Lump-Sum Investment",
-      description: "Retirement projection for a lump-sum investment in Savvly's Longevity Benefit Fund. Returns payout amounts at each milestone age (80, 85, 90, 95) with WITH-Savvly vs WITHOUT-Savvly cumulative totals, per-age breakdowns, and server-provided `_lower`/`_upper` range bounds. Use `_upper` as the central illustrative estimate and `_lower` to communicate downside. Suitable for retirement income planning, annuity alternative analysis, and longevity benefit illustration. Response embeds SEC-style disclaimers and per-field interpretation hints under `metadata`.",
+      description: "Retirement projection for a lump-sum investment in Savvly's Longevity Benefit Fund. Returns payout amounts at each milestone age (80, 85, 90, 95) with Savvly vs market alone cumulative totals, per-age breakdowns, and server-provided `_lower`/`_upper` range bounds. Use `_upper` as the central illustrative estimate and `_lower` to communicate downside. Suitable for retirement income planning, annuity alternative analysis, and longevity benefit illustration. Response embeds SEC-style disclaimers and per-field interpretation hints under `metadata`. " + SAVVLY_VS_MARKET_ALONE_PAYOUT_METHODOLOGY + " " + DISCLOSURE_REQUIRED_TERSE,
       inputSchema: {
         current_age: external_exports.number().int().min(25).max(79).describe("Investor's current age"),
         funding_amount: external_exports.number().min(100).describe("Lump sum investment in USD"),
@@ -23050,7 +23240,7 @@ function createMcpServer() {
     "project_savvly_monthly",
     {
       title: "Project Savvly Monthly Contributions",
-      description: "Retirement projection for monthly contributions to Savvly's Longevity Benefit Fund over a number of years. Returns payout amounts at milestone ages 80/85/90/95 with WITH-Savvly vs WITHOUT-Savvly cumulative totals, per-age breakdowns, and server-provided `_lower`/`_upper` range bounds. Use `_upper` as the central illustrative estimate and `_lower` to communicate downside. Suitable for retirement savings planning, annuity alternative comparison, and longevity benefit illustration. Supports an optional annual contribution increase and an optional early-withdrawal age. Disclaimers + per-field hints under `metadata`.",
+      description: "Retirement projection for monthly contributions to Savvly's Longevity Benefit Fund over a number of years. Returns payout amounts at milestone ages 80/85/90/95 with Savvly vs market alone cumulative totals, per-age breakdowns, and server-provided `_lower`/`_upper` range bounds. Use `_upper` as the central illustrative estimate and `_lower` to communicate downside. Suitable for retirement savings planning, annuity alternative comparison, and longevity benefit illustration. Supports an optional annual contribution increase and an optional early-withdrawal age. Disclaimers + per-field hints under `metadata`. " + SAVVLY_VS_MARKET_ALONE_PAYOUT_METHODOLOGY + " " + DISCLOSURE_REQUIRED_TERSE,
       inputSchema: {
         current_age: external_exports.number().int().min(25).max(79).describe("Investor's current age"),
         monthly_amount: external_exports.number().min(10).describe("Monthly contribution in USD"),
@@ -23094,7 +23284,7 @@ function createMcpServer() {
     "project_retirement_with_savvly",
     {
       title: "Project Retirement Trajectory With Savvly",
-      description: "Full retirement simulation showing the projected savings trajectory WITH and WITHOUT a Savvly allocation across the planning horizon (current_age \u2192 life_expectancy). Returns `gap_score`, `possible_higher_monthly_paycheck`, a server-provided headline message, and a per-year `age_dependent_values[]` timeline. Disclaimers + per-field hints under `metadata`.",
+      description: "Full retirement simulation showing the projected savings trajectory WITH and WITHOUT a Savvly allocation across the planning horizon (current_age \u2192 life_expectancy). Returns `gap_score`, `possible_higher_monthly_paycheck`, a server-provided headline message, and a per-year `age_dependent_values[]` timeline. Disclaimers + per-field hints under `metadata`. " + DISCLOSURE_REQUIRED_TERSE,
       inputSchema: {
         current_age: external_exports.number().int().min(25).max(79).describe("Current age"),
         retirement_age: external_exports.number().int().min(50).max(80).describe("Planned retirement age"),