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

Author: ochafik

examples/basic-server-vanillajs/server.ts

@@ -3,6 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { z } from "zod";
 import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps/server";
 import { startServer } from "./server-utils.js";
 
@@ -28,12 +29,16 @@ export function createServer(): McpServer {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       inputSchema: {},
+      outputSchema: z.object({
+        time: z.string(),
+      }),
       _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
       const time = new Date().toISOString();
       return {
-        content: [{ type: "text", text: JSON.stringify({ time }) }],
+        content: [{ type: "text", text: time }],
+        structuredContent: { time },
       };
     },
   );

examples/basic-server-vanillajs/src/mcp-app.ts

@@ -15,8 +15,8 @@ const log = {
 
 
 function extractTime(result: CallToolResult): string {
-  const { text } = result.content?.find((c) => c.type === "text")!;
-  return text;
+  const { time } = (result.structuredContent as { time?: string }) ?? {};
+  return time ?? "[ERROR]";
 }
 
 

examples/budget-allocator-server/server.ts

@@ -224,6 +224,30 @@ function generateHistory(
   return months;
 }
 
+// ---------------------------------------------------------------------------
+// Response Formatting
+// ---------------------------------------------------------------------------
+
+function formatBudgetSummary(data: BudgetDataResponse): string {
+  const lines: string[] = [
+    "Budget Allocator Configuration",
+    "==============================",
+    "",
+    `Default Budget: ${data.config.currencySymbol}${data.config.defaultBudget.toLocaleString()}`,
+    `Available Presets: ${data.config.presetBudgets.map((b) => `${data.config.currencySymbol}${b.toLocaleString()}`).join(", ")}`,
+    "",
+    "Categories:",
+    ...data.config.categories.map(
+      (c) => `  - ${c.name}: ${c.defaultPercent}% default`,
+    ),
+    "",
+    `Historical Data: ${data.analytics.history.length} months`,
+    `Benchmark Stages: ${data.analytics.stages.join(", ")}`,
+    `Default Stage: ${data.analytics.defaultStage}`,
+  ];
+  return lines.join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // MCP Server Setup
 // ---------------------------------------------------------------------------
@@ -248,6 +272,7 @@ export function createServer(): McpServer {
       description:
         "Returns budget configuration with 24 months of historical allocations and industry benchmarks by company stage",
       inputSchema: {},
+      outputSchema: BudgetDataResponseSchema,
       _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
     },
     async (): Promise<CallToolResult> => {
@@ -276,9 +301,10 @@ export function createServer(): McpServer {
         content: [
           {
             type: "text",
-            text: JSON.stringify(response),
+            text: formatBudgetSummary(response),
           },
         ],
+        structuredContent: response,
       };
     },
   );

examples/budget-allocator-server/src/mcp-app.ts

@@ -607,13 +607,7 @@ const app = new App({ name: "Budget Allocator", version: "1.0.0" });
 
 app.ontoolresult = (result) => {
   log.info("Received tool result:", result);
-  const text = result
-    .content!.filter(
-      (c): c is { type: "text"; text: string } => c.type === "text",
-    )
-    .map((c) => c.text)
-    .join("");
-  const data = JSON.parse(text) as BudgetDataResponse;
+  const data = result.structuredContent as unknown as BudgetDataResponse;
   if (data?.config && data?.analytics) {
     initializeUI(data.config, data.analytics);
   }

examples/cohort-heatmap-server/server.ts

@@ -152,6 +152,17 @@ function generateCohortData(
   };
 }
 
+function formatCohortSummary(data: CohortData): string {
+  const avgRetention = data.cohorts
+    .flatMap((c) => c.cells)
+    .filter((cell) => cell.periodIndex > 0)
+    .reduce((sum, cell, _, arr) => sum + cell.retention / arr.length, 0);
+
+  return `Cohort Analysis: ${data.cohorts.length} cohorts, ${data.periods.length} periods
+Average retention: ${(avgRetention * 100).toFixed(1)}%
+Metric: ${data.metric}, Period: ${data.periodType}`;
+}
+
 export function createServer(): McpServer {
   const server = new McpServer({
     name: "Cohort Heatmap Server",
@@ -169,6 +180,7 @@ export function createServer(): McpServer {
       description:
         "Returns cohort retention heatmap data showing customer retention over time by signup month",
       inputSchema: GetCohortDataInputSchema.shape,
+      outputSchema: CohortDataSchema.shape,
       _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
     },
     async ({ metric, periodType, cohortCount, maxPeriods }) => {
@@ -180,7 +192,8 @@ export function createServer(): McpServer {
       );
 
       return {
-        content: [{ type: "text", text: JSON.stringify(data) }],
+        content: [{ type: "text", text: formatCohortSummary(data) }],
+        structuredContent: data,
       };
     },
   );

examples/cohort-heatmap-server/src/mcp-app.tsx

@@ -123,13 +123,7 @@ function CohortHeatmapInner({
           maxPeriods: 12,
         },
       });
-      const text = result
-        .content!.filter(
-          (c): c is { type: "text"; text: string } => c.type === "text",
-        )
-        .map((c) => c.text)
-        .join("");
-      setData(JSON.parse(text) as CohortData);
+      setData(result.structuredContent as unknown as CohortData);
     } catch (e) {
       console.error("Failed to fetch cohort data:", e);
     } finally {

examples/customer-segmentation-server/server.ts

@@ -30,6 +30,29 @@ const GetCustomerDataInputSchema = z.object({
     .describe("Filter by segment (default: All)"),
 });
 
+const CustomerSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  segment: z.string(),
+  annualRevenue: z.number(),
+  employeeCount: z.number(),
+  accountAge: z.number(),
+  engagementScore: z.number(),
+  supportTickets: z.number(),
+  nps: z.number(),
+});
+
+const SegmentSummarySchema = z.object({
+  name: z.string(),
+  count: z.number(),
+  color: z.string(),
+});
+
+const GetCustomerDataOutputSchema = z.object({
+  customers: z.array(CustomerSchema),
+  segments: z.array(SegmentSummarySchema),
+});
+
 // Cache generated data for session consistency
 let cachedCustomers: Customer[] | null = null;
 let cachedSegments: SegmentSummary[] | null = null;
@@ -78,13 +101,15 @@ export function createServer(): McpServer {
         description:
           "Returns customer data with segment information for visualization. Optionally filter by segment.",
         inputSchema: GetCustomerDataInputSchema.shape,
+        outputSchema: GetCustomerDataOutputSchema.shape,
         _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
       },
       async ({ segment }): Promise<CallToolResult> => {
         const data = getCustomerData(segment);
 
         return {
           content: [{ type: "text", text: JSON.stringify(data) }],
+          structuredContent: data,
         };
       },
     );

examples/integration-server/server.ts

@@ -6,6 +6,7 @@ import type {
 } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { z } from "zod";
 import {
   registerAppTool,
   registerAppResource,
@@ -33,16 +34,21 @@ export function createServer(): McpServer {
       title: "Get Time",
       description: "Returns the current server time.",
       inputSchema: {},
+      outputSchema: z.object({
+        time: z.string(),
+      }),
       _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
     },
     async (): Promise<CallToolResult> => {
+      const time = new Date().toISOString();
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify({ time: new Date().toISOString() }),
+            text: JSON.stringify({ time }),
           },
         ],
+        structuredContent: { time },
       };
     },
   );

examples/integration-server/src/mcp-app.tsx

@@ -17,13 +17,7 @@ const log = {
 };
 
 function extractTime(callToolResult: CallToolResult): string {
-  const text = callToolResult
-    .content!.filter(
-      (c): c is { type: "text"; text: string } => c.type === "text",
-    )
-    .map((c) => c.text)
-    .join("");
-  const { time } = JSON.parse(text) as { time: string };
+  const { time } = callToolResult.structuredContent as { time: string };
   return time;
 }
 

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,
+          },
         };
       },
     );