fix: streamline scenario modeler startup

Run the scenario modeler example through the built dscode CLI so the MCP App demo works from one terminal, and shut down managed MCP processes cleanly.

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

Author: 王璨

README.md

@@ -310,6 +310,8 @@ Always push the branch before creating a PR.
 
 `examples/` 提供可直接运行的示例项目，用来演示 dscode 的 MCP 集成方式和交互式 UI 能力。
 
+### MCP App
+
 | 示例 | 说明 | 快速开始 |
 | --- | --- | --- |
 | `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

@@ -7,23 +7,25 @@ A SaaS financial scenario modeler MCP App. Interactive 12-month projections with
 ```bash
 cd examples/scenario-modeler
 npm install
+npm --prefix ../.. run build
 npm start
 ```
 
-Server starts on http://localhost:3100/mcp
-
-## Connect to dscode
-
-```
-/config mcp add scenario-modeler --url http://localhost:3100/mcp
-```
+`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."
 
-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.
+If the agent replies with plain text only, ask it to use the `get-scenario-data` MCP tool explicitly.
 
 Agent calls `get-scenario-data` → dscode renders the MCP App → TUI highlights the localhost link → open it in your browser.
 
+## Alternate startup modes
+
+```bash
+npm run start:server   # start only the HTTP MCP server on localhost:3100
+npm run start:stdio    # start only the stdio MCP server
+```
+
 ## How it works
 
 - **server.ts** — Standard MCP server using `@modelcontextprotocol/sdk`. Registers:

examples/scenario-modeler/package.json

@@ -5,7 +5,8 @@
   "type": "module",
   "description": "SaaS Scenario Modeler MCP App — dscode example",
   "scripts": {
-    "start": "tsx server.ts",
+    "start": "node ../../dist/dscode.mjs",
+    "start:server": "tsx server.ts",
     "start:stdio": "tsx server.ts --stdio",
     "demo": "tsx ../../src/core/main.ts",
     "demo:server": "tsx server.ts"

examples/scenario-modeler/server.ts

@@ -202,7 +202,8 @@ function createServer(): McpServer {
 }
 
 async function startHttp() {
-  const app = createMcpExpressApp({ host: "0.0.0.0" });
+  const host = process.env.SCENARIO_MODELER_HOST ?? "127.0.0.1";
+  const app = createMcpExpressApp({ host });
   app.use(cors());
   app.all("/mcp", async (req: any, res: any) => {
     const srv = createServer();
@@ -211,7 +212,7 @@ async function startHttp() {
     await srv.connect(t);
     await t.handleRequest(req, res, req.body);
   });
-  const port = 3100;
+  const port = Number(process.env.PORT ?? 3100);
   app.listen(port, () => console.log(`MCP Server → http://localhost:${port}/mcp`));
 }
 

src/core/main.ts

@@ -45,4 +45,7 @@ async function main(): Promise<void> {
   process.exit(0);
 }
 
-main();
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

src/mcp/client.ts

@@ -34,7 +34,6 @@ export class MCPClient {
       await this.connectSSE();
     }
 
-    // send initialize with MCP Apps ui extension capability
     const result = await this.request("initialize", {
       protocolVersion: MCP_PROTOCOL_VERSION,
       capabilities: {
@@ -52,7 +51,6 @@ export class MCPClient {
       throw new Error(`MCP server "${this.config.name}" returned invalid initialize response`);
     }
 
-    // send initialized notification
     this.sendNotification("notifications/initialized");
   }
 
@@ -88,21 +86,22 @@ export class MCPClient {
     if (this.closed) return;
     this.closed = true;
 
-    try {
-      await this.request("shutdown", undefined, 5_000);
-    } catch {
-      // ignore shutdown errors
+    if (this.config.transport === "stdio") {
+      this.killProcessTree();
+    } else {
+      try {
+        await this.request("shutdown", undefined, 1_000);
+      } catch {
+      }
     }
 
-    // clear pending
     for (const [, entry] of this.pending) {
       clearTimeout(entry.timer);
       entry.reject(new Error("MCP client closed"));
     }
     this.pending.clear();
 
     if (this.process) {
-      this.process.kill();
       this.process = null;
     }
   }
@@ -115,6 +114,7 @@ export class MCPClient {
     this.process = spawn(cmd, expandedArgs, {
       stdio: ["pipe", "pipe", "pipe"],
       env: { ...process.env, ...this.config.env },
+      detached: process.platform !== "win32",
     });
 
     // Suppress EPIPE errors on stdin when the child process exits unexpectedly
@@ -237,22 +237,19 @@ export class MCPClient {
               const dataMatch = line.match(/^data:\s*(.+)/);
 
               if (eventMatch && eventMatch[1] === "endpoint") {
-                // wait for the next data line with the actual endpoint URL
                 continue;
               }
 
               if (dataMatch) {
                 try {
                   const data = JSON.parse(dataMatch[1]);
                   if (data.method === "endpoint") {
-                    // SSE endpoint for sending messages back
                     this.sseUrl = data.params?.endpoint ?? null;
                     resolve();
                   } else {
                     this.handleMessage(dataMatch[1]);
                   }
                 } catch {
-                  // not JSON, skip
                 }
               }
             }
@@ -279,6 +276,18 @@ export class MCPClient {
     });
   }
 
+  private killProcessTree(): void {
+    if (!this.process?.pid) return;
+    try {
+      if (process.platform !== "win32") {
+        process.kill(-this.process.pid, "SIGTERM");
+      } else {
+        this.process.kill("SIGTERM");
+      }
+    } catch {
+    }
+  }
+
   private handleMessage(raw: string): void {
     let msg: any;
     try {
@@ -329,7 +338,6 @@ export class MCPClient {
       if (this.config.transport === "stdio") {
         this.process?.stdin?.write(msg + "\n");
       } else if (this.sseUrl) {
-        // POST to SSE endpoint
         const parsed = new URL(this.sseUrl, this.config.url);
         const requester = parsed.protocol === "https:" ? httpsRequest : httpRequest;
         const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
@@ -340,8 +348,7 @@ export class MCPClient {
             method: "POST",
             headers: { "Content-Type": "application/json" },
           },
-          (res) => {
-            // response comes via SSE stream, handled in handleMessage
+          () => {
           },
         );
         req.on("error", (err) => {