Add multi-view app architecture reference for build-mcp-app (#973)

Adds a reference doc covering production patterns for multi-view MCP apps
that go beyond single-purpose widgets. Patterns distilled from building
nashville-charts-app, generalized with placeholder examples.

Covers: single-resource action dispatch, model context updates, teardown
guards, bidirectional tool calls, Vite+esbuild build pipeline, dual
transport (HTTP+stdio), debugging tips, prompt orchestration.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

external_plugins/discord/server.ts

@@ -25,7 +25,7 @@ import {
   type Attachment,
 } from 'discord.js'
 import { randomBytes } from 'crypto'
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync, chmodSync } from 'fs'
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync } from 'fs'
 import { homedir } from 'os'
 import { join, sep } from 'path'
 
@@ -37,8 +37,6 @@ const ENV_FILE = join(STATE_DIR, '.env')
 // Load ~/.claude/channels/discord/.env into process.env. Real env wins.
 // Plugin-spawned servers don't get an env block — this is where the token lives.
 try {
-  // Token is a credential — lock to owner. No-op on Windows (would need ACLs).
-  chmodSync(ENV_FILE, 0o600)
   for (const line of readFileSync(ENV_FILE, 'utf8').split('\n')) {
     const m = line.match(/^(\w+)=(.*)$/)
     if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2]

external_plugins/discord/skills/configure/SKILL.md

@@ -80,8 +80,7 @@ as the correct long-term choice. Don't skip the lockdown offer.
 2. `mkdir -p ~/.claude/channels/discord`
 3. Read existing `.env` if present; update/add the `DISCORD_BOT_TOKEN=` line,
    preserve other keys. Write back, no quotes around the value.
-4. `chmod 600 ~/.claude/channels/discord/.env` — the token is a credential.
-5. Confirm, then show the no-args status so the user sees where they stand.
+4. Confirm, then show the no-args status so the user sees where they stand.
 
 ### `clear` — remove the token
 

external_plugins/telegram/server.ts

@@ -18,7 +18,7 @@ import {
 import { Bot, InputFile, type Context } from 'grammy'
 import type { ReactionTypeEmoji } from 'grammy/types'
 import { randomBytes } from 'crypto'
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync, chmodSync } from 'fs'
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, renameSync, realpathSync } from 'fs'
 import { homedir } from 'os'
 import { join, extname, sep } from 'path'
 
@@ -30,8 +30,6 @@ const ENV_FILE = join(STATE_DIR, '.env')
 // Load ~/.claude/channels/telegram/.env into process.env. Real env wins.
 // Plugin-spawned servers don't get an env block — this is where the token lives.
 try {
-  // Token is a credential — lock to owner. No-op on Windows (would need ACLs).
-  chmodSync(ENV_FILE, 0o600)
   for (const line of readFileSync(ENV_FILE, 'utf8').split('\n')) {
     const m = line.match(/^(\w+)=(.*)$/)
     if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2]
@@ -341,7 +339,7 @@ const mcp = new Server(
     instructions: [
       'The sender reads Telegram, not this session. Anything you want them to see must go through the reply tool — your transcript output never reaches their chat.',
       '',
-      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. If the tag has attachment_file_id, call download_attachment with that file_id to fetch the file, then Read the returned path. Reply with the reply tool — pass chat_id back. Use reply_to (set to a message_id) only when replying to an earlier message; the latest message doesn\'t need a quote-reply, omit reply_to for normal responses.',
+      'Messages from Telegram arrive as <channel source="telegram" chat_id="..." message_id="..." user="..." ts="...">. If the tag has an image_path attribute, Read that file — it is a photo the sender attached. Reply with the reply tool — pass chat_id back. Use reply_to (set to a message_id) only when replying to an earlier message; the latest message doesn\'t need a quote-reply, omit reply_to for normal responses.',
       '',
       'reply accepts file paths (files: ["/abs/path.png"]) for attachments. Use react to add emoji reactions, and edit_message to update a message you previously sent (e.g. progress → result).',
       '',
@@ -389,17 +387,6 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['chat_id', 'message_id', 'emoji'],
       },
     },
-    {
-      name: 'download_attachment',
-      description: 'Download a file attachment from a Telegram message to the local inbox. Use when the inbound <channel> meta shows attachment_file_id. Returns the local file path ready to Read. Telegram caps bot downloads at 20MB.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          file_id: { type: 'string', description: 'The attachment_file_id from inbound meta' },
-        },
-        required: ['file_id'],
-      },
-    },
     {
       name: 'edit_message',
       description: 'Edit a message the bot previously sent. Useful for progress updates (send "working…" then edit to the result).',
@@ -491,24 +478,6 @@ mcp.setRequestHandler(CallToolRequestSchema, async req => {
         ])
         return { content: [{ type: 'text', text: 'reacted' }] }
       }
-      case 'download_attachment': {
-        const file_id = args.file_id as string
-        const file = await bot.api.getFile(file_id)
-        if (!file.file_path) throw new Error('Telegram returned no file_path — file may have expired')
-        const url = `https://api.telegram.org/file/bot${TOKEN}/${file.file_path}`
-        const res = await fetch(url)
-        if (!res.ok) throw new Error(`download failed: HTTP ${res.status}`)
-        const buf = Buffer.from(await res.arrayBuffer())
-        // file_path is from Telegram (trusted), but strip to safe chars anyway
-        // so nothing downstream can be tricked by an unexpected extension.
-        const rawExt = file.file_path.includes('.') ? file.file_path.split('.').pop()! : 'bin'
-        const ext = rawExt.replace(/[^a-zA-Z0-9]/g, '') || 'bin'
-        const uniqueId = (file.file_unique_id ?? '').replace(/[^a-zA-Z0-9_-]/g, '') || 'dl'
-        const path = join(INBOX_DIR, `${Date.now()}-${uniqueId}.${ext}`)
-        mkdirSync(INBOX_DIR, { recursive: true })
-        writeFileSync(path, buf)
-        return { content: [{ type: 'text', text: path }] }
-      }
       case 'edit_message': {
         assertAllowedChat(args.chat_id as string)
         const edited = await bot.api.editMessageText(
@@ -566,94 +535,10 @@ bot.on('message:photo', async ctx => {
   })
 })
 
-bot.on('message:document', async ctx => {
-  const doc = ctx.message.document
-  const name = safeName(doc.file_name)
-  const text = ctx.message.caption ?? `(document: ${name ?? 'file'})`
-  await handleInbound(ctx, text, undefined, {
-    kind: 'document',
-    file_id: doc.file_id,
-    size: doc.file_size,
-    mime: doc.mime_type,
-    name,
-  })
-})
-
-bot.on('message:voice', async ctx => {
-  const voice = ctx.message.voice
-  const text = ctx.message.caption ?? '(voice message)'
-  await handleInbound(ctx, text, undefined, {
-    kind: 'voice',
-    file_id: voice.file_id,
-    size: voice.file_size,
-    mime: voice.mime_type,
-  })
-})
-
-bot.on('message:audio', async ctx => {
-  const audio = ctx.message.audio
-  const name = safeName(audio.file_name)
-  const text = ctx.message.caption ?? `(audio: ${safeName(audio.title) ?? name ?? 'audio'})`
-  await handleInbound(ctx, text, undefined, {
-    kind: 'audio',
-    file_id: audio.file_id,
-    size: audio.file_size,
-    mime: audio.mime_type,
-    name,
-  })
-})
-
-bot.on('message:video', async ctx => {
-  const video = ctx.message.video
-  const text = ctx.message.caption ?? '(video)'
-  await handleInbound(ctx, text, undefined, {
-    kind: 'video',
-    file_id: video.file_id,
-    size: video.file_size,
-    mime: video.mime_type,
-    name: safeName(video.file_name),
-  })
-})
-
-bot.on('message:video_note', async ctx => {
-  const vn = ctx.message.video_note
-  await handleInbound(ctx, '(video note)', undefined, {
-    kind: 'video_note',
-    file_id: vn.file_id,
-    size: vn.file_size,
-  })
-})
-
-bot.on('message:sticker', async ctx => {
-  const sticker = ctx.message.sticker
-  const emoji = sticker.emoji ? ` ${sticker.emoji}` : ''
-  await handleInbound(ctx, `(sticker${emoji})`, undefined, {
-    kind: 'sticker',
-    file_id: sticker.file_id,
-    size: sticker.file_size,
-  })
-})
-
-type AttachmentMeta = {
-  kind: string
-  file_id: string
-  size?: number
-  mime?: string
-  name?: string
-}
-
-// Filenames and titles are uploader-controlled. They land inside the <channel>
-// notification — delimiter chars would let the uploader break out of the tag
-// or forge a second meta entry.
-function safeName(s: string | undefined): string | undefined {
-  return s?.replace(/[<>\[\]\r\n;]/g, '_')
-}
-
 async function handleInbound(
   ctx: Context,
   text: string,
   downloadImage: (() => Promise<string | undefined>) | undefined,
-  attachment?: AttachmentMeta,
 ): Promise<void> {
   const result = gate(ctx)
 
@@ -701,13 +586,6 @@ async function handleInbound(
         user_id: String(from.id),
         ts: new Date((ctx.message?.date ?? 0) * 1000).toISOString(),
         ...(imagePath ? { image_path: imagePath } : {}),
-        ...(attachment ? {
-          attachment_kind: attachment.kind,
-          attachment_file_id: attachment.file_id,
-          ...(attachment.size != null ? { attachment_size: String(attachment.size) } : {}),
-          ...(attachment.mime ? { attachment_mime: attachment.mime } : {}),
-          ...(attachment.name ? { attachment_name: attachment.name } : {}),
-        } : {}),
       },
     },
   })

external_plugins/telegram/skills/configure/SKILL.md

@@ -77,8 +77,7 @@ offer.
 2. `mkdir -p ~/.claude/channels/telegram`
 3. Read existing `.env` if present; update/add the `TELEGRAM_BOT_TOKEN=` line,
    preserve other keys. Write back, no quotes around the value.
-4. `chmod 600 ~/.claude/channels/telegram/.env` — the token is a credential.
-5. Confirm, then show the no-args status so the user sees where they stand.
+4. Confirm, then show the no-args status so the user sees where they stand.
 
 ### `clear` — remove the token
 

plugins/mcp-server-dev/skills/build-mcp-app/SKILL.md

@@ -350,3 +350,4 @@ The `sleep` keeps stdin open long enough to collect all responses. Parse the jso
 - `references/iframe-sandbox.md` — CSP/sandbox constraints, the bundle-inlining pattern, image handling
 - `references/widget-templates.md` — reusable HTML scaffolds for picker / confirm / progress / display
 - `references/apps-sdk-messages.md` — the `App` class API: widget ↔ host ↔ server messaging
+- `references/app-architecture-patterns.md` — multi-view app patterns: action dispatch, model context, build pipeline, dual transport

plugins/mcp-server-dev/skills/build-mcp-app/references/app-architecture-patterns.md

@@ -0,0 +1,381 @@
+# Multi-View App Architecture
+
+When a single-purpose widget isn't enough — when you have 5+ UI tools that share styling, state patterns, or a data model — consider building a **multi-view MCP app**: one React (or framework) SPA that dispatches to the right view based on which tool was called.
+
+This doc covers the production patterns for that architecture. It assumes you've read the main `build-mcp-app` skill and the `widget-templates.md` reference.
+
+> **Reference implementation:** [`nashville-charts-app`](https://github.com/bryankthompson/nashville-charts-app) on GitHub / npm demonstrates every pattern below. Install with `npx nashville-charts-app --stdio`.
+
+---
+
+## Single resource, action-dispatched views
+
+Instead of one HTML file per tool, register **one shared resource** and point all UI tools at it. Each tool returns JSON with an `action` field that tells the app which view to render.
+
+**Server side:**
+
+```typescript
+const RESOURCE_URI = "ui://my-app/app.html";
+
+// Tool A — returns action + data
+registerAppTool(server, "show_dashboard", {
+  description: "Show the analytics dashboard",
+  inputSchema: { range: z.enum(["week", "month"]) },
+  _meta: { ui: { resourceUri: RESOURCE_URI } },
+}, async ({ range }) => {
+  const stats = await fetchStats(range);
+  return {
+    content: [{ type: "text", text: JSON.stringify({ action: "dashboard", stats }) }],
+  };
+});
+
+// Tool B — same resource, different action
+registerAppTool(server, "show_details", {
+  description: "Show detail view for a specific item",
+  inputSchema: { id: z.string() },
+  _meta: { ui: { resourceUri: RESOURCE_URI } },
+}, async ({ id }) => {
+  const item = await fetchItem(id);
+  return {
+    content: [{ type: "text", text: JSON.stringify({ action: "detail", item }) }],
+  };
+});
+
+// One resource serves all views
+registerAppResource(server, "App", RESOURCE_URI, {},
+  async () => ({
+    contents: [{ uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: appHtml }],
+  }),
+);
+```
+
+**Widget side (React):**
+
+```tsx
+function App() {
+  const [view, setView] = useState(null);
+  const { app } = useApp({
+    appInfo: { name: "MyApp", version: "1.0.0" },
+    onAppCreated: (app) => {
+      app.ontoolresult = async (result) => {
+        const data = JSON.parse(result.content[0].text);
+        if (data.action) setView(data);
+      };
+    },
+  });
+
+  if (!view) return <div>Waiting for tool call...</div>;
+
+  switch (view.action) {
+    case "dashboard": return <Dashboard stats={view.stats} app={app} />;
+    case "detail":    return <DetailView item={view.item} app={app} />;
+    default:          return <div>Unknown view</div>;
+  }
+}
+```
+
+**Why this beats multiple HTML files:**
+- Shared CSS, shared components, shared state (theme, loading indicators)
+- One build artifact to deploy and cache
+- Consistent UX across all views — users don't see a flash between different iframes
+- The dispatch is just a `switch` on a string — trivial to extend
+
+---
+
+## Model context updates
+
+`updateModelContext()` tells the LLM what the user is currently looking at — without adding a visible message to the chat. This is critical for multi-step workflows where Claude needs to reason about the current UI state.
+
+**What to send:** Structured state, not a prose description. YAML or JSON works well.
+
+```tsx
+useEffect(() => {
+  if (!view || !app) return;
+
+  const ctx = {
+    view: view.action,
+    ...(view.action === "dashboard" && {
+      range: view.stats.range,
+      itemCount: view.stats.items.length,
+    }),
+    ...(view.action === "detail" && {
+      itemId: view.item.id,
+      itemName: view.item.name,
+    }),
+  };
+
+  app.updateModelContext({
+    content: [{ type: "text", text: JSON.stringify(ctx) }],
+  }).catch(() => {
+    // Host may not support updateModelContext — degrade silently
+  });
+}, [app, view]);
+```
+
+**When to send:** On every view change. Don't send on every keystroke or scroll — just when the semantic state changes (new view, new data, user selection).
+
+**Always catch:** Not all hosts support `updateModelContext()`. Wrap in `.catch()` so the app doesn't break in hosts that don't implement it.
+
+---
+
+## Teardown guards
+
+After the host calls `onteardown`, other callbacks (`ontoolresult`, `onhostcontextchanged`) may still fire. Without a guard, these late callbacks can cause React state updates on an unmounted component.
+
+```tsx
+const tornDown = useRef(false);
+
+app.onteardown = async () => {
+  tornDown.current = true;
+  setView(null);
+  return {};
+};
+
+app.ontoolresult = async (result) => {
+  if (tornDown.current) return;  // Guard
+  const data = JSON.parse(result.content[0].text);
+  if (data.action) setView(data);
+};
+
+app.onhostcontextchanged = () => {
+  if (tornDown.current) return;  // Guard
+  setHostContext(app.getHostContext());
+};
+```
+
+Use a `useRef` (not `useState`) — refs update synchronously and don't trigger re-renders.
+
+---
+
+## Bidirectional tool calls from components
+
+When a UI component needs to call a server tool (e.g., a "Transpose" button, a "Load More" link), use `app.callServerTool()` and flow the result back through the parent's dispatch.
+
+```tsx
+// Parent holds the dispatch
+function App() {
+  const handleToolResult = useCallback((result) => {
+    const data = JSON.parse(result.content[0].text);
+    if (data.action) setView(data);
+  }, []);
+
+  return <DetailView item={view.item} app={app} onToolResult={handleToolResult} />;
+}
+
+// Child calls tools, parent re-dispatches
+function DetailView({ item, app, onToolResult }) {
+  const [loading, setLoading] = useState(false);
+
+  const handleRefresh = async () => {
+    setLoading(true);
+    try {
+      const result = await app.callServerTool({
+        name: "show_details",
+        arguments: { id: item.id },
+      });
+      onToolResult(result);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div>
+      <h1>{item.name}</h1>
+      <button onClick={handleRefresh} disabled={loading}>
+        {loading ? "Loading..." : "Refresh"}
+      </button>
+    </div>
+  );
+}
+```
+
+**Pattern:** Components don't set the view directly — they call tools and the parent handles the result. This keeps the data flow unidirectional: tool result -> parent dispatch -> child render.
+
+**App-only tools:** For tools that should only be callable from the widget (not by the LLM), use `server.registerTool` (not `registerAppTool` — these tools don't render a UI resource) with `visibility: ["app"]`:
+
+```typescript
+server.registerTool("internal_action", {
+  description: "...",
+  inputSchema: { ... },
+  _meta: { ui: { visibility: ["app"] } },
+}, handler);
+```
+
+---
+
+## Build pipeline: Vite + esbuild
+
+A multi-view app needs a framework build (React, Vue, etc.) bundled into a single HTML file, plus a separate server bundle. Two-step build:
+
+**Step 1 — Vite bundles the SPA into one HTML file:**
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  plugins: [react(), viteSingleFile()],
+  build: {
+    rollupOptions: { input: process.env.INPUT },  // e.g., INPUT=app.html
+    outDir: "dist",
+    emptyOutDir: false,  // Don't delete dist — esbuild writes here too
+  },
+});
+```
+
+`vite-plugin-singlefile` inlines all JS and CSS into the HTML. The output is a self-contained `dist/app.html` — no external chunks, no asset files.
+
+**Step 2 — esbuild bundles the server:**
+
+```bash
+# Server module
+npx esbuild server/server.ts --bundle --platform=node --format=esm \
+  --outfile=dist/server.js --packages=external
+
+# CLI entry point (with shebang for npx)
+npx esbuild main.ts --bundle --platform=node --format=esm \
+  --outfile=dist/index.js --packages=external \
+  --banner:js='#!/usr/bin/env node'
+```
+
+`--packages=external` keeps npm dependencies as imports (not bundled). The shebang banner makes `dist/index.js` directly executable.
+
+**Combined build script:**
+
+```json
+{
+  "build": "cross-env INPUT=app.html vite build && npx esbuild server/server.ts --bundle --platform=node --format=esm --outfile=dist/server.js --packages=external && npx esbuild main.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external --banner:js='#!/usr/bin/env node'"
+}
+```
+
+**Path resolution (dev vs. prod):**
+
+```typescript
+// Works in both TypeScript (dev) and compiled JS (prod)
+const DIST_DIR = import.meta.filename.endsWith(".ts")
+  ? path.join(import.meta.dirname, "..", "dist")   // Running .ts directly
+  : import.meta.dirname;                             // Running compiled .js
+
+const appHtml = await fs.promises.readFile(
+  path.join(DIST_DIR, "app.html"), "utf-8"
+);
+```
+
+---
+
+## Dual transport: HTTP + stdio
+
+Support both transports from one codebase. Use a server factory function and a CLI flag.
+
+```typescript
+// main.ts
+import { createServer } from "./server/server.js";
+
+const useStdio = process.argv.includes("--stdio");
+
+if (useStdio) {
+  startStdio(createServer);
+} else {
+  startHTTP(createServer);
+}
+```
+
+**HTTP (stateless, one server per request):**
+
+```typescript
+async function startHTTP(createServer) {
+  const app = express();
+  app.use(express.json());
+
+  app.all("/mcp", async (req, res) => {
+    const server = createServer();  // Fresh per request
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,  // Stateless
+    });
+    res.on("close", () => {
+      transport.close();
+      server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  app.listen(process.env.PORT ?? 3001);
+}
+```
+
+**stdio (persistent, one server for the session):**
+
+```typescript
+async function startStdio(createServer) {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Server stays alive until the process exits
+}
+```
+
+**Graceful shutdown** for HTTP:
+
+```typescript
+const shutdown = () => {
+  httpServer.close(() => process.exit(0));
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+```
+
+---
+
+## Debugging tips
+
+**Keep stdout clean.** In stdio mode, stdout IS the MCP protocol. All debug output must go to stderr:
+
+```typescript
+console.error("[DEBUG] Tool called:", toolName);  // stderr — safe
+console.log("...");                                // stdout — breaks protocol
+```
+
+**Extension detection.** The MCP SDK's Zod schema strips unknown fields from `capabilities` — including `extensions`, which signals UI support. To check if the client supports your widgets, intercept raw messages before SDK parsing:
+
+```typescript
+transport.onmessage = (msg) => {
+  if (msg?.method === "initialize") {
+    const extensions = msg.params?.capabilities?.extensions;
+    if (extensions) {
+      console.error("[DEBUG] Client supports extensions:", JSON.stringify(extensions));
+    }
+  }
+};
+```
+
+Compare raw messages with SDK-parsed `server.getClientCapabilities()` to diagnose stripping.
+
+**Resource caching in Claude Desktop.** After editing widget HTML, fully quit (Cmd+Q) and relaunch. Window-close doesn't clear the resource cache.
+
+---
+
+## Prompt templates as workflow orchestration
+
+MCP prompts can guide the LLM through multi-tool workflows — acting as lightweight choreography:
+
+```typescript
+server.registerPrompt("analyze_pipeline", {
+  title: "Run Full Analysis",
+  description: "Fetch data, visualize, and summarize",
+}, () => ({
+  messages: [{
+    role: "user",
+    content: {
+      type: "text",
+      text: "Run a full analysis: use fetch-data to pull the latest numbers, " +
+            "show-dashboard to visualize them, then summarize the key insights.",
+    },
+  }],
+}));
+```
+
+The prompt tells the LLM which tools to call in which order. No dynamic data — just instructions. This surfaces as a slash-command in hosts that support prompts, giving users a one-click workflow trigger.