feat: use structuredContent with outputSchema in example servers (#220)

* build app-with-deps

* make registerAppTool more interchangeable w/ server.registerTool

* feat: use structuredContent in all example servers

All servers now return structuredContent alongside JSON text content.
All mcp-apps now read structuredContent directly (no JSON.parse fallback).

Updated servers:
- basic-server-vanillajs
- budget-allocator-server
- cohort-heatmap-server
- customer-segmentation-server
- integration-server
- scenario-modeler-server
- system-monitor-server
- threejs-server
- video-resource-server
- wiki-explorer-server

* feat: add outputSchema to all example servers

Define output schemas for structuredContent validation:
- basic-server-vanillajs: { time: string }
- budget-allocator-server: BudgetDataResponseSchema
- cohort-heatmap-server: CohortDataSchema
- customer-segmentation-server: customers/segments schema
- integration-server: { time: string }
- scenario-modeler-server: templates/defaultInputs schema
- system-monitor-server: SystemStatsSchema
- threejs-server: { code, height }
- video-resource-server: { videoUri, description }
- wiki-explorer-server: { page, links, error }

* prettier:fix

* make registerAppTool more interchangeable w/ server.registerTool

* feat: use structuredContent in all example servers

All servers now return structuredContent alongside JSON text content.
All mcp-apps now read structuredContent directly (no JSON.parse fallback).

Updated servers:
- basic-server-vanillajs
- budget-allocator-server
- cohort-heatmap-server
- customer-segmentation-server
- integration-server
- scenario-modeler-server
- system-monitor-server
- threejs-server
- video-resource-server
- wiki-explorer-server

* feat: add outputSchema to all example servers

Define output schemas for structuredContent validation:
- basic-server-vanillajs: { time: string }
- budget-allocator-server: BudgetDataResponseSchema
- cohort-heatmap-server: CohortDataSchema
- customer-segmentation-server: customers/segments schema
- integration-server: { time: string }
- scenario-modeler-server: templates/defaultInputs schema
- system-monitor-server: SystemStatsSchema
- threejs-server: { code, height }
- video-resource-server: { videoUri, description }
- wiki-explorer-server: { page, links, error }

* prettier:fix

* revert: remove unrelated workflow, version, and arch changes

* chore: update package-lock.json

* refactor(basic-server-vanillajs): address PR review comments

- Simplify server.ts to return plain time string in text content (not JSON),
  matching the quickstart guide pattern
- Add defensive coding in mcp-app.ts with optional chaining and fallback
  to handle potential type mismatches gracefully

* refactor: restore rich text formatting for LLM-readable content

Restore the human-readable text formatting functions that were removed,
providing meaningful summaries in the text content while keeping
structuredContent for programmatic UI consumption:

- budget-allocator-server: formatBudgetSummary with config overview
- cohort-heatmap-server: formatCohortSummary with retention stats
- scenario-modeler-server: formatScenarioSummary with financial metrics

examples/scenario-modeler-server/server.ts

@@ -64,6 +64,13 @@ const GetScenarioDataInputSchema = z.object({
   ),
 });
 
+const GetScenarioDataOutputSchema = z.object({
+  templates: z.array(ScenarioTemplateSchema),
+  defaultInputs: ScenarioInputsSchema,
+  customProjections: z.array(MonthlyProjectionSchema).optional(),
+  customSummary: ScenarioSummarySchema.optional(),
+});
+
 // Types derived from schemas
 type ScenarioInputs = z.infer<typeof ScenarioInputsSchema>;
 type MonthlyProjection = z.infer<typeof MonthlyProjectionSchema>;
@@ -243,6 +250,37 @@ const DEFAULT_INPUTS: ScenarioInputs = {
   fixedCosts: 30000,
 };
 
+// ============================================================================
+// Formatters for text output
+// ============================================================================
+
+function formatCurrency(value: number): string {
+  const absValue = Math.abs(value);
+  const sign = value < 0 ? "-" : "";
+  if (absValue >= 1_000_000) {
+    return `${sign}$${(absValue / 1_000_000).toFixed(2)}M`;
+  }
+  if (absValue >= 1_000) {
+    return `${sign}$${(absValue / 1_000).toFixed(1)}K`;
+  }
+  return `${sign}$${Math.round(absValue)}`;
+}
+
+function formatScenarioSummary(
+  summary: ScenarioSummary,
+  label: string,
+): string {
+  return [
+    `${label}:`,
+    `  Ending MRR: ${formatCurrency(summary.endingMRR)}`,
+    `  ARR: ${formatCurrency(summary.arr)}`,
+    `  Total Revenue: ${formatCurrency(summary.totalRevenue)}`,
+    `  Total Profit: ${formatCurrency(summary.totalProfit)}`,
+    `  MRR Growth: ${summary.mrrGrowthPct.toFixed(1)}%`,
+    `  Break-even: ${summary.breakEvenMonth ? `Month ${summary.breakEvenMonth}` : "Not achieved"}`,
+  ].join("\n");
+}
+
 // ============================================================================
 // MCP Server
 // ============================================================================
@@ -269,6 +307,7 @@ export function createServer(): McpServer {
         description:
           "Returns SaaS scenario templates and optionally computes custom projections for given inputs",
         inputSchema: GetScenarioDataInputSchema.shape,
+        outputSchema: GetScenarioDataOutputSchema.shape,
         _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
       },
       async (args: {
@@ -278,18 +317,28 @@ export function createServer(): McpServer {
           ? calculateScenario(args.customInputs)
           : undefined;
 
+        const text = [
+          "SaaS Scenario Modeler",
+          "=".repeat(40),
+          "",
+          "Available Templates:",
+          ...SCENARIO_TEMPLATES.map(
+            (t) => `  ${t.icon} ${t.name}: ${t.description}`,
+          ),
+          "",
+          customScenario
+            ? formatScenarioSummary(customScenario.summary, "Custom Scenario")
+            : "Use customInputs parameter to compute projections for a specific scenario.",
+        ].join("\n");
+
         return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                templates: SCENARIO_TEMPLATES,
-                defaultInputs: DEFAULT_INPUTS,
-                customProjections: customScenario?.projections,
-                customSummary: customScenario?.summary,
-              }),
-            },
-          ],
+          content: [{ type: "text", text }],
+          structuredContent: {
+            templates: SCENARIO_TEMPLATES,
+            defaultInputs: DEFAULT_INPUTS,
+            customProjections: customScenario?.projections,
+            customSummary: customScenario?.summary,
+          },
         };
       },
     );

examples/scenario-modeler-server/src/mcp-app.tsx

@@ -1,6 +1,5 @@
 import type { McpUiHostContext } from "@modelcontextprotocol/ext-apps";
 import { useApp } from "@modelcontextprotocol/ext-apps/react";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { StrictMode, useState, useMemo, useCallback, useEffect } from "react";
 import { createRoot } from "react-dom/client";
 import { SliderRow } from "./components/SliderRow.tsx";
@@ -25,18 +24,6 @@ interface CallToolResultData {
   defaultInputs?: ScenarioInputs;
 }
 
-/** Extract templates and defaultInputs from tool result content */
-function extractResultData(result: CallToolResult): CallToolResultData {
-  const text = result
-    .content!.filter(
-      (c): c is { type: "text"; text: string } => c.type === "text",
-    )
-    .map((c) => c.text)
-    .join("");
-  const { templates, defaultInputs } = JSON.parse(text) as CallToolResultData;
-  return { templates, defaultInputs };
-}
-
 const APP_INFO = { name: "SaaS Scenario Modeler", version: "1.0.0" };
 
 function getSafeAreaPaddingStyle(hostContext?: McpUiHostContext) {
@@ -70,7 +57,8 @@ function ScenarioModeler() {
     capabilities: {},
     onAppCreated: (app) => {
       app.ontoolresult = async (result) => {
-        const { templates, defaultInputs } = extractResultData(result);
+        const { templates, defaultInputs } =
+          result.structuredContent as unknown as CallToolResultData;
         if (templates) setTemplates(templates);
         if (defaultInputs) setDefaultInputs(defaultInputs);
       };