用户                    Web UI                Host                Widget(iframe)         MCP Server
 │                        │                    │                       │                    │
 │ 输入"查看Tokyo天气"     │                    │                       │                    │
 │──────────────────────▶│                    │                       │                    │
 │                        │  把 prompt 转给模型 │                       │                    │
 │                        │───────────────────▶│                      │                    │
 │                        │                    │ 模型决定调 show_weather│                    │
 │                        │                    │─────────────────────────────────────────▶ │
 │                        │                    │                       │     server 执行    │
 │                        │                    │                       │     回 toolResult  │
 │                        │                    │◀──────────────────────────────────────────│
 │                        │                    │ 看到 _meta.ui          │                   │
 │                        │                    │ 预取 widget HTML       │                   │
 │                        │                    │──────────────────────────────────────────▶│
 │                        │                    │◀──────────────────────────────────────────│
 │                        │                    │ 在工具调用消息里附带    │                    │
 │                        │                    │ widget 元信息         │                    │
 │                        │◀───────────────────│                      │                    │
 │                        │ 渲染 sandbox iframe│                       │                    │
 │                        │ 注入 HTML + CSP    │                       │                    │
 │                        │──────────────────────────────────────────▶│                    │
 │                        │                    │                       │  initialize        │
 │                        │                    │◀─────────────────────│                    │
 │                        │                    │ 推送 toolResult       │                    │
 │                        │                    │─────────────────────▶│                    │
 │                        │                    │ 推送 hostContext.theme │                   │
 │                        │                    │─────────────────────▶│                    │
 │ 看到天气仪表盘 ✓        │                    │                       │ 应用主题、渲染 UI   │
 │                        │                    │                       │                    │
 │ 点击 "San Francisco"   │                    │                       │                    │
 │───────────────────────────────────────────────────────────────────▶│                    │
 │                        │                    │                       │ 调 tools/call      │
 │                        │                    │◀──────────────────────│ get_weather(SF)   │
 │                        │ ⚠ 弹框：是否允许？ │                       │                    │
 │ 点 "允许"              │                    │                       │                    │
 │──────────────────────▶│                    │                       │                    │
 │                        │                    │ 转发给 server         │                    │
 │                        │                    │─────────────────────────────────────────▶ │
 │                        │                    │◀──────────────────────────────────────────│
 │                        │                    │ 把结果回给 widget      │                    │
 │                        │                    │─────────────────────▶│                    │
 │ 看到 SF 的天气 ✓        │                    │                       │ 局部刷新           │

const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
} = require('@modelcontextprotocol/sdk/types.js');

const UI_MIME = 'text/html;profile=mcp-app';
const TODO_URI = 'ui://my-todo/list';

const server = new Server(
  { name: 'my-todo', version: '0.1.0' },
  { capabilities: { tools: {}, resources: {} } },
);

const todos = [];

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'show_todos',
      description: 'Show interactive todo list widget',
      inputSchema: { type: 'object', properties: {} },
      // 关键：声明 UI Resource，host 见到此字段就渲染 widget
      _meta: { ui: { resourceUri: TODO_URI } },
    },
    {
      name: 'add_todo',
      description: 'Add a new todo',
      inputSchema: {
        type: 'object',
        properties: { title: { type: 'string' } },
        required: ['title'],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async req => {
  if (req.params.name === 'show_todos') {
    return {
      content: [{ type: 'text', text: `${todos.length} todos` }],
      // structuredContent 会自动作为 toolResult 推送给 widget
      structuredContent: { items: todos },
      // 关键：tool result 也带 _meta.ui，让 host 关联到 widget
      _meta: { ui: { resourceUri: TODO_URI } },
    };
  }
  if (req.params.name === 'add_todo') {
    todos.push({ id: todos.length + 1, title: req.params.arguments.title });
    return {
      content: [{ type: 'text', text: 'Added' }],
      structuredContent: { items: todos },
    };
  }
});

server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [{ uri: TODO_URI, name: 'todo-list', mimeType: UI_MIME }],
}));

server.setRequestHandler(ReadResourceRequestSchema, async req => {
  if (req.params.uri === TODO_URI) {
    return {
      contents: [{
        uri: TODO_URI,
        text: HTML,           // 见下面 HTML 模板
        mimeType: UI_MIME,
        _meta: {
          ui: {
            // CSP：声明 widget 运行时需要的外部域名，host 会注入到 iframe 的
            // <meta http-equiv="Content-Security-Policy">。**未列出的域名将被浏览器拦截。**
            csp: {
              // 允许通过 ESM 远端引入 ext-apps（script-src / connect-src 都需要 esm.sh）
              resourceDomains: ['https://esm.sh'],
              // 如 widget 还会调外部 API（fetch / WebSocket），把对应域名加这里
              connectDomains: ['https://esm.sh'],
            },
            permissions: {},     // 默认 sandbox：allow-scripts allow-same-origin allow-forms
            prefersBorder: true, // host 给 iframe 加 1px 描边，便于视觉区分
          },
        },
      }],
    };
  }
});

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />

  <!--
    CSP：与资源 _meta.ui.csp 中声明的域名保持一致。
    host 会按 _meta.ui.csp 自动注入 script-src / connect-src 的白名单，
    但写在 HTML 里的 <meta> 优先生效，建议同步声明，方便本地直接预览。
  -->
  <meta http-equiv="Content-Security-Policy"
        content="default-src 'self' 'unsafe-inline';
                 script-src 'self' 'unsafe-inline' https://esm.sh;
                 connect-src 'self' https://esm.sh;
                 img-src 'self' data: blob:;
                 style-src 'self' 'unsafe-inline';">

  <style>
    /* 主题双层适配（详见“主题适配”一节） */
    :root {
      color-scheme: light dark;
      --bg: light-dark(#fff, #1e1e1e);
      --fg: light-dark(#1a1a1a, #e6e6e6);
    }
    html[data-theme="light"] { color-scheme: light }
    html[data-theme="dark"]  { color-scheme: dark }
    body { margin: 0; padding: 12px; background: var(--bg); color: var(--fg); }
  </style>
</head>
<body>
  <ul id="list"></ul>

  <script type="module">
    // 远端 ESM 引入 ext-apps（自带依赖的 bundle，浏览器直接 import）
    // 锁版本到 1.x 以避免上游 breaking change；生产环境建议改成具体 patch 版（如 @1.7.4）
    import { App } from 'https://esm.sh/@modelcontextprotocol/ext-apps@1/app-with-deps';

    const app = new App({
      name: 'todo-widget',
      version: '1.0.0',
      autoResize: true,        // 自动按内容上报 size-changed
    });

    function render(items) {
      const list = document.getElementById('list');
      list.textContent = '';
      for (const t of items) {
        const li = document.createElement('li');
        li.textContent = t.title;
        list.appendChild(li);
      }
    }

    // 模型调 show_todos 时把 toolResult 推送过来
    app.ontoolresult = (r) => {
      if (r?.structuredContent?.items) render(r.structuredContent.items);
    };

    // 主题：拿到 hostContext.theme 后写 data-theme + style.colorScheme
    function applyTheme(theme) {
      if (!theme) return;
      document.documentElement.setAttribute('data-theme', theme);
      document.documentElement.style.colorScheme = theme;
    }
    app.onhostcontextchanged = (ctx) => applyTheme(ctx?.theme);

    await app.connect();
    applyTheme(app.hostContext?.theme);
  </script>
</body>
</html>

{
  "mcpServers": {
    "my-todo": {
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}

{
  "mcpServers": {
    "my-todo": {
      "type": "http",
      "url": "http://127.0.0.1:8801/mcp"
    }
  }
}

// ~/.codebuddy/settings.json
{
  "permissions": {
    "allow": [
      "mcp__my-todo",                 // 整个 server 的所有工具放行
      "mcp__github__list_issues",     // 仅放行 github server 的 list_issues
      "mcp__github__get_pr_diff"
    ],
    "deny": [
      "mcp__github__delete_repo"      // 即便 server 整体放行，也能精准 deny 单个工具
    ]
  }
}

codebuddy --allowed-tools "mcp__my-todo,mcp__github__list_issues" "..."

:root {
  color-scheme: light dark;
  --bg: light-dark(#fff, #1e1e1e);
  --fg: light-dark(#1a1a1a, #e6e6e6);
  --border: light-dark(#ddd, #3a3a3a);
}

/* 当 JS 锁定 data-theme 后，覆盖 light-dark() 自动取值 */
html[data-theme="light"] { color-scheme: light }
html[data-theme="dark"]  { color-scheme: dark }

body { background: var(--bg); color: var(--fg); }

function applyTheme(theme) {
  if (!theme) return;  // 没拿到就别动 DOM，让 CSS light-dark() 兜底接管
  document.documentElement.setAttribute('data-theme', theme);
  document.documentElement.style.colorScheme = theme;
}

applyTheme(app.hostContext?.theme);
app.onhostcontextchanged = (ctx) => applyTheme(ctx?.theme);

app.log({ level: 'info', logger: 'my-widget', data: { foo: 'bar' } });