feat(web): MCP App HTML inline rendering in web chat + port conflict handling

- Add mcp_app WebSocket event to stream MCP app URLs to web frontend
- WebUiBackend proxies AppHostManager routes for same-origin iframe embedding
- ToolCard renders expandable iframe when tool has MCP app
- Friendly EADDRINUSE error message instead of crash
- Fix mcp_app toolName mismatch (prefixed vs original name)
- Register mcp-app.html as MCP resource in scenario-modeler example
- Update README, AGENTS.md, example docs
- Compress and add screen shots (web-ui.gif, mcp-app.gif)

Author: 王璨

AGENTS.md

@@ -43,6 +43,7 @@ Agent Loop (pi-agent-core，已有)
 | `src/mcp/` | MCP 客户端（stdio/SSE）+ 管理器 | `client.ts`, `manager.ts`, `types.ts` |
 | `src/permissions/` | 权限拦截（deny/ask/allow） | `manager.ts`, `rules.ts` |
 | `src/ui/` | REPL、流式渲染、slash commands | `tui-app.ts`, `conversation.ts`, `commands.ts` |
+| `web/` | Web 前端（独立 Vite + React 项目） | `src/components/`, `src/hooks/`, `src/types/` |
 
 ## 内置驱动 (Drivers)
 
@@ -54,6 +55,8 @@ Agent Loop (pi-agent-core，已有)
 
 MCP 服务器连接后也会注册为驱动，source 为 `"mcp"`。
 
+`web/` 放在根目录而非 `src/` 下，因为它是独立的 Vite + React 项目，有自己的 `tsconfig.json`、`package.json`、`vite.config.ts`，不和 `src/` 共用 tsc 构建。构建产物输出到 `dist/web/`，由 dscode 的 HTTP server 直接 serve。
+
 ## 关键 Hook 接线
 
 ```typescript
@@ -84,6 +87,8 @@ new Agent({
 
 ```bash
 npm start          # 本地开发：启动交互式 REPL
+npm start -- --web  # Web 模式：浏览器中对话
+npm run build:web   # 构建前端（npm start 前需先执行）
 npm run typecheck  # 类型检查
 npm test           # 运行测试
 ```

README.md

@@ -111,7 +111,13 @@ npm run build:web             # 先构建前端
 node dist/dscode.mjs --web    # 启动 Web 模式
 ```
 
-浏览器打开 `http://localhost:3000` 即可使用。Web UI 包含：
+浏览器打开 `http://localhost:3000` 即可使用：
+
+<p align="center">
+  <img src="docs/screen_shots/web-ui.gif" alt="DSCode Web UI" width="720" />
+</p>
+
+Web UI 包含：
 
 | 功能 | 说明 |
 | --- | --- |
@@ -367,6 +373,12 @@ Always push the branch before creating a PR.
 | --- | --- | --- |
 | `examples/scenario-modeler` | 一个 SaaS 场景建模 MCP Server。演示 tool 返回 `structuredContent` / `isError` 后，dscode 如何渲染 MCP App；没有 server HTML 时走 MDX，有 HTML resource 时优先使用 server 自带页面。 | `cd examples/scenario-modeler && npm install && npm start` |
 
+<p align="center">
+  <img src="docs/screen_shots/mcp-app.gif" alt="MCP App 演示" width="720" />
+</p>
+
+> 上图演示了 scenario-modeler 在 Web UI 中内联展示 MCP App HTML —— 点击 "Open App ▼" 即可展开交互式 SaaS 财务建模仪表盘。
+
 更多使用说明见：
 - `examples/scenario-modeler/README.md`
 

docs/screen_shots/mcp-app.gif

@@ -4,52 +4,58 @@ A SaaS financial scenario modeler MCP App. Interactive 12-month projections with
 
 ## Quick Start
 
+### CLI Mode (TUI)
+
 ```bash
 cd examples/scenario-modeler
 npm install
 npm --prefix ../.. run build
 npm start
 ```
 
-`npm start` launches the current repo build of dscode from this example directory. dscode then starts the `scenario-modeler` MCP server through the existing stdio MCP config, so you only need one terminal.
-
-Then ask the agent: "Show me the current SaaS scenario projections."
-
-If the agent replies with plain text only, ask it to use the `get-scenario-data` MCP tool explicitly.
+Then ask: "Show me the current SaaS scenario projections."
 
 Agent calls `get-scenario-data` → dscode renders the MCP App → TUI highlights the localhost link → open it in your browser.
 
-## Alternate startup modes
+### Web Mode
+
+Run from the example directory so dscode picks up the local `.dscode/settings.json`:
 
 ```bash
-npm run start:server   # start only the HTTP MCP server on localhost:3100
-npm run start:stdio    # start only the stdio MCP server
+cd examples/scenario-modeler
+npm install
+npm --prefix ../.. run build
+npm --prefix ../.. run build:web
+npm start -- --web --web-port 3000
 ```
 
-## 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"`
-  - 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
+> `npm start` runs `node ../../dist/dscode.mjs` from the current directory — no `--prefix` needed, so cwd stays as `examples/scenario-modeler` and the local MCP config is loaded.
 
-## Features
+Open `http://localhost:3000`, then ask: "Show me the current SaaS scenario projections."
 
-- 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)
-- Custom projection computation via tool arguments
-- Light/dark theme support (via CSS custom properties)
+When the agent calls `get-scenario-data`, the MCP App renders **inline in the chat** — click **"Open App ▼"** to expand the interactive dashboard with sliders, chart, and templates.
 
-## Transport
+## Alternate startup
 
 ```bash
-npm start          # HTTP (default, port 3100)
-npm run start:stdio  # stdio for direct MCP client connection
+npm run start:server   # HTTP MCP server only (localhost:3100)
+npm run start:stdio    # stdio MCP server only
 ```
+
+## How it works
+
+- **server.ts** — MCP server using `@modelcontextprotocol/sdk`. Registers:
+  - `get-scenario-data` tool with `_meta.ui.resourceUri = "ui://scenario-modeler/mcp-app"`
+  - `mcp-app.html` as a UI resource (`text/html;profile=mcp-app`)
+  - `structuredContent` + `_ui.mdx` for MDX auto-layout fallback
+- **mcp-app.html** — Pure JS dashboard with Canvas chart, 5 sliders, template comparison, postMessage bridge
+- **Web inline rendering** — iframe embedded in the tool card, communicating via SSE bridge
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `server.ts` | MCP server with tool + resource registration |
+| `mcp-app.html` | Interactive dashboard (served as MCP resource) |
+| `package.json` | Dependencies and scripts |
+| `.dscode/settings.json` | MCP config (loaded when running from this directory) |

docs/screen_shots/web-ui.gif

@@ -4,6 +4,9 @@
  * Registration: server.tool() + server.resource() with _meta.ui
  * No @modelcontextprotocol/ext-apps dependency.
  */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
@@ -195,7 +198,22 @@ function createServer(): McpServer {
     },
   );
 
-  // No s.resource() call — dscode renders this example from structuredContent.
+  // No s.registerResource() call — dscode renders this example from structuredContent.
+
+  // Register UI resource — serves mcp-app.html as the MCP App UI
+  const mcpAppHtml = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "mcp-app.html"), "utf-8");
+  s.registerResource(
+    "Scenario Modeler App",
+    URI,
+    {
+      mimeType: "text/html;profile=mcp-app",
+      description: "Interactive SaaS financial scenario modeler",
+      _meta: { ui: { domain: "mcp-app", prefersBorder: false } },
+    },
+    async () => ({
+      contents: [{ uri: URI, mimeType: "text/html;profile=mcp-app", text: mcpAppHtml }],
+    }),
+  );
   // The example includes a server-provided _ui.mdx override to avoid nested object cells.
 
   return s;

examples/scenario-modeler/README.md

@@ -31,7 +31,7 @@ export class Harness {
   private skillManager: SkillManager;
   private permissionManager: PermissionManager;
   private mcpManager?: MCPManager;
-  private appHostManager?: AppHostManager;
+  public appHostManager?: AppHostManager;
   private config: HarnessConfig;
   private ui!: UiBackend;
   private baseSystemPrompt = "";

examples/scenario-modeler/server.ts

@@ -71,6 +71,10 @@ async function main(): Promise<void> {
       harness,
       config,
     });
+    // Pass AppHostManager to web backend so MCP apps can be served
+    if (harness.appHostManager) {
+      webUi.setAppHostManager(harness.appHostManager);
+    }
     await harness.run(webUi);
   } else {
     // CLI mode: default TuiBackend

src/core/harness.ts

@@ -52,6 +52,12 @@ export interface ConfigData {
   maxTokens: number;
 }
 
+export interface McpAppInfo {
+  toolName: string;
+  appUrl: string;
+  resourceUri: string;
+}
+
 export type ServerEvent =
   | { type: "ready"; model: string; config: ConfigData; messages: ConversationMessage[] }
   | { type: "user_message"; text: string }
@@ -69,7 +75,8 @@ export type ServerEvent =
   | { type: "sessions"; data: SessionInfo[] }
   | { type: "mcp_state"; servers: McpServerInfo[] }
   | { type: "model"; name: string }
-  | { type: "slash_result"; text: string };
+  | { type: "slash_result"; text: string }
+  | { type: "mcp_app"; app: McpAppInfo };
 
 export interface ConversationMessage {
   role: "user" | "assistant" | "system";
@@ -83,4 +90,5 @@ export interface ToolCallEntry {
   args: string;
   result: string;
   isError: boolean;
+  mcpApp?: McpAppInfo;
 }