feat: add MDX MCP app rendering workflow

Add the MDX-based MCP app host/runtime, scenario-modeler example updates, tests, and root README examples documentation. This keeps server-provided HTML as the preferred path while enabling structuredContent-driven UI fallback.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: 王璨

README.md

@@ -306,6 +306,17 @@ Always push the branch before creating a PR.
 | `DSCODE_CONFIG_HOME` | 自定义配置目录（默认 `~/.dscode`） |
 | `DSCODE_DATA_HOME` | 自定义数据目录（默认 `~/.dscode`） |
 
+## Examples
+
+`examples/` 提供可直接运行的示例项目，用来演示 dscode 的 MCP 集成方式和交互式 UI 能力。
+
+| 示例 | 说明 | 快速开始 |
+| --- | --- | --- |
+| `examples/scenario-modeler` | 一个 SaaS 场景建模 MCP Server。演示 tool 返回 `structuredContent` 后，dscode 如何渲染 MCP App；没有 server HTML 时走 MDX，有 HTML resource 时优先使用 server 自带页面。 | `cd examples/scenario-modeler && npm install && npm start` |
+
+更多使用说明见：
+- `examples/scenario-modeler/README.md`
+
 ## Project structure
 
 ```text
@@ -316,7 +327,7 @@ src/
 ├── memory/         # 跨 session 记忆
 ├── drivers/        # 驱动注册 + 内置驱动 (fs, shell, search)
 ├── skills/         # Skill 管理器 + SKILL.md 加载器
-├── mcp/            # MCP 客户端（stdio/SSE）+ 管理器
+├── mcp/            # MCP 客户端（stdio/SSE）+ 管理器 + MCP App host/runtime
 ├── permissions/    # 权限拦截
 └── ui/             # REPL、流式渲染、slash commands
 ```

examples/scenario-modeler/README.md

@@ -18,28 +18,32 @@ Server starts on http://localhost:3100/mcp
 /config mcp add scenario-modeler --url http://localhost:3100/mcp
 ```
 
-Then ask the agent: "Show me the SaaS scenario modeler"
+Then ask the agent: "Show me the current SaaS scenario projections."
 
-Agent calls `get-scenario-data` → dscode fetches the UI HTML → TUI displays a localhost URL → open in browser.
+That phrasing is more natural, but still points the agent toward the `get-scenario-data` MCP tool because it asks for live scenario output rather than code analysis or setup help.
+
+Agent calls `get-scenario-data` → dscode renders the MCP App → TUI highlights the localhost link → open it in your browser.
 
 ## How it works
 
 - **server.ts** — Standard MCP server using `@modelcontextprotocol/sdk`. Registers:
   - `get-scenario-data` tool with `_meta.ui.resourceUri = "ui://scenario-modeler/mcp-app"`
-  - `ui://scenario-modeler/mcp-app` resource returning `mcp-app.html`
-- **mcp-app.html** — Single-file interactive View. Zero external dependencies.
-  - MCP protocol handshake via postMessage
-  - Canvas API for projection chart
-  - DOM API for sliders and metric cards
-  - Local calculation for instant feedback
+  - Returns `structuredContent` with templates, projections, and summary data
+  - Includes `_ui.mdx` to demonstrate a custom MDX layout override
+  - **No HTML required** — dscode renders the dashboard from data + MDX
+- **Auto-generated UI** — dscode inspects `structuredContent` and renders:
+  - Chart from projection arrays (line chart with MRR/netProfit curves)
+  - Metrics cards from summary key-value pairs
+  - Table from template/projection data
+- **No external dependencies** — UI is rendered by dscode's built-in MDX Runtime
 
 ## Features
 
-- 5 sliders: Starting MRR, Growth Rate, Churn Rate, Gross Margin, Fixed Costs
-- 12-month line chart (MRR, Gross Profit, Net Profit)
+- 12-month line chart (MRR, Gross Profit, Net Profit) — auto-generated from data
+- Metric cards showing ending MRR, ARR, total revenue, profit, growth %, break-even
 - 5 pre-built templates (Bootstrapped, VC Rocketship, Cash Cow, Turnaround, Efficient Growth)
-- Template comparison with dashed overlay lines
-- Light/dark theme support
+- Custom projection computation via tool arguments
+- Light/dark theme support (via CSS custom properties)
 
 ## Transport
 

examples/scenario-modeler/server.ts

@@ -10,8 +10,6 @@ import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import cors from "cors";
 import { z } from "zod";
-import fs from "node:fs";
-import path from "node:path";
 
 // ============================================================================
 // Types & Business Logic (adapted from ext-apps scenario-modeler)
@@ -88,8 +86,60 @@ const TEMPLATES: ScenarioTemplate[] = [
 
 const DEFAULT: ScenarioInputs = { startingMRR: 50000, monthlyGrowthRate: 5, monthlyChurnRate: 3, grossMargin: 80, fixedCosts: 30000 };
 
+const DEFAULT_PROJECTIONS = calculateProjections(DEFAULT);
+const DEFAULT_SUMMARY = calculateSummary(DEFAULT_PROJECTIONS, DEFAULT);
+
 const URI = "ui://scenario-modeler/mcp-app";
-const MT = "text/html;profile=mcp-app";
+
+const SCENARIO_MODELER_MDX = `
+<Card title="SaaS Scenario Modeler">
+  <Card title="Current Scenario Inputs">
+    <Metrics items={inputMetrics}/>
+  </Card>
+  <Card title="12-Month Projection">
+    <Chart type="line" data={activeProjections} x="month" y={["mrr","grossProfit","netProfit"]}/>
+    <Metrics items={summaryMetrics}/>
+    <Table rows={activeProjections}/>
+  </Card>
+  <Card title="Scenario Templates">
+    <Table rows={templateRows}/>
+  </Card>
+</Card>
+`.trim();
+
+function formatTemplateRows(templates: ScenarioTemplate[]) {
+  return templates.map((template) => ({
+    icon: template.icon,
+    name: template.name,
+    description: template.description,
+    keyInsight: template.keyInsight,
+    breakEven: template.summary.breakEvenMonth ? `Month ${template.summary.breakEvenMonth}` : "Not achieved",
+    endingMRR: fmt(template.summary.endingMRR),
+    arr: fmt(template.summary.arr),
+  }));
+}
+
+function formatInputsMetrics(inputs: ScenarioInputs) {
+  return {
+    startingMRR: fmt(inputs.startingMRR),
+    monthlyGrowthRate: `${inputs.monthlyGrowthRate}%`,
+    monthlyChurnRate: `${inputs.monthlyChurnRate}%`,
+    grossMargin: `${inputs.grossMargin}%`,
+    fixedCosts: fmt(inputs.fixedCosts),
+  };
+}
+
+function formatSummaryMetrics(summary: ScenarioSummary) {
+  return {
+    endingMRR: fmt(summary.endingMRR),
+    arr: fmt(summary.arr),
+    totalRevenue: fmt(summary.totalRevenue),
+    totalProfit: fmt(summary.totalProfit),
+    mrrGrowth: `${summary.mrrGrowthPct}%`,
+    avgMargin: `${summary.avgMargin}%`,
+    breakEven: summary.breakEvenMonth ? `Month ${summary.breakEvenMonth}` : "Not achieved",
+  };
+}
 
 // ============================================================================
 // MCP Server Registration (standard SDK — no ext-apps wrapper)
@@ -101,33 +151,52 @@ function createServer(): McpServer {
   s.registerTool("get-scenario-data",
     {
       title: "Get Scenario Data",
-      description: "Get SaaS financial scenario templates and optionally compute custom 12-month projections. Returns data for the interactive dashboard.",
+      description: "Get SaaS financial scenario templates and optionally compute custom 12-month projections. Returns data for the interactive dashboard. Call with customInputs omitted (or empty object) to get templates with defaults.",
       inputSchema: {
         customInputs: z.object({
-          startingMRR: z.number().describe("Starting MRR ($)"),
-          monthlyGrowthRate: z.number().describe("Growth rate (%)"),
-          monthlyChurnRate: z.number().describe("Churn rate (%)"),
-          grossMargin: z.number().describe("Gross margin (%)"),
-          fixedCosts: z.number().describe("Fixed costs ($)"),
-        }).optional().describe("Custom scenario parameters to compute projections for"),
+          startingMRR: z.number().optional().describe("Starting MRR ($)"),
+          monthlyGrowthRate: z.number().optional().describe("Growth rate (%)"),
+          monthlyChurnRate: z.number().optional().describe("Churn rate (%)"),
+          grossMargin: z.number().optional().describe("Gross margin (%)"),
+          fixedCosts: z.number().optional().describe("Fixed costs ($)"),
+        }).optional().describe("Custom scenario parameters. Omit all fields to use defaults."),
       },
       _meta: { ui: { resourceUri: URI, visibility: ["model", "app"] } } as any,
     },
-    async (args: { customInputs?: ScenarioInputs }) => {
-      const custom = args.customInputs;
-      const cp = custom ? calculateProjections(custom) : undefined;
-      const cs = cp ? calculateSummary(cp, custom!) : undefined;
+    async (args: { customInputs?: Partial<ScenarioInputs> }) => {
+      const raw = args.customInputs;
+      const custom: ScenarioInputs | undefined = raw
+        ? {
+            startingMRR: raw.startingMRR ?? DEFAULT.startingMRR,
+            monthlyGrowthRate: raw.monthlyGrowthRate ?? DEFAULT.monthlyGrowthRate,
+            monthlyChurnRate: raw.monthlyChurnRate ?? DEFAULT.monthlyChurnRate,
+            grossMargin: raw.grossMargin ?? DEFAULT.grossMargin,
+            fixedCosts: raw.fixedCosts ?? DEFAULT.fixedCosts,
+          }
+        : undefined;
+      const activeInputs = custom ?? DEFAULT;
+      const activeProjections = custom ? calculateProjections(custom) : DEFAULT_PROJECTIONS;
+      const activeSummary = custom ? calculateSummary(activeProjections, activeInputs) : DEFAULT_SUMMARY;
       const lines = ["SaaS Scenario Modeler", "=".repeat(40), "", "Templates:"];
       for (const t of TEMPLATES) lines.push(`  ${t.icon} ${t.name}: ${t.description}`);
-      if (cs) lines.push("", "Custom:", `  Ending MRR: ${fmt(cs.endingMRR)}`, `  ARR: ${fmt(cs.arr)}`);
-      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: { templates: TEMPLATES, defaultInputs: DEFAULT, customProjections: cp, customSummary: cs } };
+      if (custom) lines.push("", "Custom:", `  Ending MRR: ${fmt(activeSummary.endingMRR)}`, `  ARR: ${fmt(activeSummary.arr)}`);
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        structuredContent: {
+          _ui: { mdx: SCENARIO_MODELER_MDX },
+          templateRows: formatTemplateRows(TEMPLATES),
+          inputMetrics: formatInputsMetrics(activeInputs),
+          summaryMetrics: formatSummaryMetrics(activeSummary),
+          activeProjections,
+          defaultInputs: DEFAULT,
+          customInputs: custom ?? null,
+        },
+      };
     },
   );
 
-  s.resource(URI, URI, { mimeType: MT, description: "Scenario Modeler UI" }, async () => {
-    const html = fs.readFileSync(path.join(import.meta.dirname, "mcp-app.html"), "utf-8");
-    return { contents: [{ uri: URI, mimeType: MT, text: html }] };
-  });
+  // No s.resource() call — dscode renders this example from structuredContent.
+  // The example includes a server-provided _ui.mdx override to avoid nested object cells.
 
   return s;
 }

openspec/changes/archive/2026-05-18-dynamic-mcp-ui-mdx-renderer/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-16

openspec/changes/archive/2026-05-18-dynamic-mcp-ui-mdx-renderer/design.md

@@ -0,0 +1,135 @@
+## Context
+
+Current MCP App flow requires Server to provide `mcp-app.html` via `resources/read`. dscode's `AppHostManager` fetches it, registers an app, and serves it through a sandbox proxy. This works but forces every Server developer to write HTML — even for simple data-display tools.
+
+The proposal introduces a browser-side MDX Runtime that auto-generates UIs from `structuredContent`, eliminating the Server HTML requirement. Server can still provide HTML (backward compatible) or opt into auto-layout with optional MDX overrides.
+
+## Goals / Non-Goals
+
+**Goals:**
+1. Auto-generate interactive UIs from `structuredContent` without Server-provided HTML
+2. Ship a lightweight MDX Runtime (Chart, Metrics, Table, Slider, Card, Row) in the sandbox
+3. Support Server-provided MDX overrides (`_ui.mdx`) for custom layouts
+4. Backward compatible — existing `mcp-app.html` Servers continue working
+5. example `scenario-modeler` works with zero HTML
+
+**Non-Goals:**
+- No React/Vue/JS framework dependency
+- No LLM involvement in UI generation (deterministic, fast)
+- No build step for the MDX Runtime (plain JS, concatenated into sandbox)
+- No drag-and-drop or WYSIWYG editing
+- Not replacing the sandbox architecture (postMessage ↔ bridge remains)
+
+## Decisions
+
+### 1. MDX Runtime: Hand-written parser, not React MDX
+
+**Choice**: Write a ~200-line tag parser that recognizes `<Chart/>`, `<Metrics/>`, etc., with inline JSON data binding. No JSX compilation.
+
+```
+Input:  `<Chart type="line" data={projections} x="month" y={["mrr","netProfit"]}/>`
+Parser:  match <Chart ... /> → extract props → resolve data bindings
+Output:  Canvas element with bound data
+```
+
+**Alternative**: Full MDX/React compiler (esbuild + MDX plugin). Too heavy for a single-file sandbox runtime.
+
+**Rationale**: The component surface is tiny (6 components), data is pre-loaded JSON, event model is minimal. A simple regex-based parser suffices.
+
+### 2. MDX Runtime delivery: Injected into sandbox.html
+
+**Choice**: Bundle the MDX Runtime (parser + 6 components) as a single JS string, inject into `sandbox.html` at serve time. The sandbox page detects data mode vs HTML mode.
+
+```
+sandbox.html (template with injection point)
+  ├── <style> ... </style>
+  ├── <script>/* MDX_RUNTIME_PLACEHOLDER */</script>  ← injected at serve time
+  └── <script>
+        if (dataMode) {
+          parseMDX(layout, data);
+          renderComponents();
+        } else {
+          // legacy: injectApp() with srcdoc
+        }
+      </script>
+```
+
+**Alternative**: Serve MDX Runtime as a separate .js file. Adds a network request, CSP complexity.
+
+**Rationale**: Single HTML response, zero extra requests. CSP stays simple (`connect-src 'self'`). Works when the page is a static file too (dev mode).
+
+### 3. Auto-layout inference: heuristic rules
+
+**Choice**: Inspect `structuredContent` shape and apply priority-ordered rules:
+
+```
+Rule 1: { x: number[], y: number[] } or array of { label, value } → Metrics cards
+Rule 2: Array of objects with numeric fields → Table
+Rule 3: Array of objects where one field is sequential (month, date) and others numeric → Chart + Table
+Rule 4: Object with nested arrays and numeric summaries → Chart + Metrics + Table combo
+Rule 5: Flat key-value → Cards
+```
+
+**Alternative**: Machine learning model. Overkill, unpredictable, no training data.
+
+**Rationale**: 80% of tool results fall into these patterns. Simple heuristics cover the common cases.
+
+### 4. Server MDX override: `_ui.mdx` in structuredContent
+
+**Choice**: If `structuredContent._ui.mdx` is a string, use it as the layout. Data bindings reference sibling keys in `structuredContent`.
+
+```json
+{
+  "structuredContent": {
+    "templates": [...],
+    "projections": [...],
+    "summary": {...},
+    "_ui": {
+      "mdx": "<Metrics data={summary}/>\n<Chart data={projections} x=\"month\" y={[\"mrr\",\"netProfit\"]}/>",
+      "bindings": {}
+    }
+  }
+}
+```
+
+**Alternative**: Namespace the data under a `data` key. But current tools return data at the top level.
+
+**Rationale**: Minimal Server-side change — just add a string. No new protocol fields needed (SDK doesn't need updating).
+
+### 5. Backward compatibility: Phase detection
+
+**Choice**: `checkAndRegisterApp` detects whether the tool has a UI resource:
+
+```
+if (resourceUri) {
+  fetchUiResource(html) → legacy mode (srcdoc)
+} else if (result.structuredContent) {
+  generateMDXLayout(data) → data mode (MDX Runtime)
+} else {
+  skip (text-only result)
+}
+```
+
+**Rationale**: No breaking change. Existing Servers with `s.resource()` continue working. New Servers just omit the resource and get auto-layout.
+
+### 6. Component Canvas: Canvas 2D (same as current)
+
+**Choice**: Chart component uses Canvas 2D API, same approach as current `mcp-app.html`.
+
+**Alternative**: SVG. More DOM elements, harder to animate, no real advantage for simple line/bar charts.
+
+**Rationale**: Proven, already works in sandbox, zero dependencies.
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Auto-layout produces wrong chart type | Server can override with `_ui.mdx` |
+| MDX parser too simple for edge cases | Component surface is tiny; escape to raw HTML is always available |
+| Runtime JS bundle increases page size | MDX Runtime is ~15KB uncompressed (~5KB gzipped), acceptable for a single-page tool |
+| Inference heuristics miss important data patterns | Add rules incrementally; scope to common SaaS/data patterns first |
+
+## Open Questions
+
+- Should the MDX Runtime support `<Form/>` for input-bound tools? (defer to future change)
+- Should we support themes (light/dark)? (yes, reuse sandbox CSS variables)

openspec/changes/archive/2026-05-18-dynamic-mcp-ui-mdx-renderer/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+Currently MCP App Views require MCP Server developers to hand-write a complete HTML file (`mcp-app.html`) for each tool. This creates unnecessary friction: a simple data-returning tool needs a whole frontend page just to display results. dscode should dynamically generate interactive UIs from tool result data, eliminating the need for Server-provided HTML in the common case.
+
+## What Changes
+
+- **Built-in MDX renderer**: dscode ships a lightweight MDX runtime component system (`<Chart/>`, `<Metrics/>`, `<Table/>`, `<Slider/>`, `<Card/>`, `<Row/>`) for rendering MCP tool results
+- **Auto-layout inference**: When a tool returns `structuredContent` without an explicit UI resource, dscode inspects the data structure and generates a default layout using built-in components
+- **Optional MDX override**: Server can include an `_ui.mdx` string in `structuredContent` to override the auto-generated layout, giving full control without writing HTML
+- **No Server HTML required**: `mcp-app.html` becomes optional; `examples/scenario-modeler/server.ts` no longer needs `s.resource()` for UI
+- **All rendering runs in-browser**: MDX Runtime is injected into the sandbox page, parsed and rendered client-side for instant interactivity (sliders, chart updates)
+
+## Capabilities
+
+### New Capabilities
+
+- `mdx-runtime`: Lightweight MDX-like parser and component renderer (Chart, Metrics, Table, Slider, Card, Row) running in the browser sandbox, capable of transforming structured data into interactive HTML
+- `auto-layout-inference`: Heuristic engine that inspects `structuredContent` shape and selects appropriate MDX components and layout (array → Table, numeric series → Chart, key-value pairs → Metrics cards)
+- `server-ui-override`: Server can optionally include `_ui.mdx` in `structuredContent` to provide explicit layout instructions, overriding auto-inference
+
+### Modified Capabilities
+
+- `mcp-app-sandbox-host`: Sandbox proxy page now includes the MDX Runtime JS bundle and supports both srcdoc (legacy HTML) and data-driven (MDX + data) rendering modes
+
+## Impact
+
+- **New files**: `src/ui/mdx/parser.ts` (MDX parser), `src/ui/mdx/components.ts` (built-in components), `src/ui/mdx/renderer.ts` (runtime orchestrator), `src/ui/mdx/inference.ts` (auto-layout engine)
+- **Modified**: `src/apps/host.ts` (generate MDX+data when no HTML resource), `src/apps/sandbox.html` (include MDX runtime, support data mode)
+- **Modified**: `examples/scenario-modeler/server.ts` (remove `s.resource()` and `mcp-app.html` dependency)
+- **Removed**: `examples/scenario-modeler/mcp-app.html` (replaced by auto-generated MDX)
+- **No new dependencies**: MDX parser is hand-written (~200 lines), no React/MDX libraries required