> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# MCP Apps Inspector

内置 MCP Apps Inspector 用于查看工具、执行请求和预览 UI。运行 `modern dev` 后，打开启动日志中的 Inspector 地址，默认是 `http://localhost:8080/mcp/inspector`。Inspector 页面仅在开发环境生成，生产构建不包含该入口。

## Inspector 工作区

Inspector 页面采用三栏布局，各栏可以独立滚动，窄屏会自动堆叠：

| 区域 | 功能                       |
| -- | ------------------------ |
| 左侧 | 搜索与选择工具，在工具列表下方编辑参数并执行调用 |
| 中间 | 展示真实 UI 卡片，支持卡片中的后续工具交互  |
| 右侧 | 查看请求日志和最近一次工具调用的完整响应     |

ENDPOINT 默认展示当前服务的完整地址，例如 `http://localhost:8080/mcp`。进入页面自动连接并选择第一个工具，但不会自动执行业务工具。可以修改地址后手动重新连接。

## 根据 inputSchema 填写参数

选择工具后，Inspector 页面读取 `inputSchema.properties`，展示字段名、类型、必填或可选标记及字段描述，并生成可编辑的 JSON 参数模板。生成值优先使用 default、examples、const 或 enum，其他字段使用占位值。存在 required 列表时，模板包含必填字段和带默认值的字段，可选字段仍可按需手动添加。

以 `greet` 为例，将生成的空字符串替换为名称：

```json
{
  "name": "Ada"
}
```

参数区接受标准 JSON，key 和字符串都必须使用双引号，不能填写 JavaScript 对象字面量 `{name: 'Ada'}`。模板用于辅助填写，不保证满足全部 Schema 约束，仍需按业务要求编辑。展开 **Tool schema and UI resource** 可以查看完整 Schema。

## 调用工具并预览卡片

1. 进入页面后自动连接默认 MCP endpoint 并读取工具列表。失败重试或修改地址后，点击 **Connect & discover** 重新连接。
2. 选择工具，展开 **Tool schema and UI resource** 查看参数定义和 UI 资源 URI。
3. 在 **Arguments (JSON)** 中填写工具参数，例如 `greet` 的 `{"name":"Ada"}`。
4. 点击 **Run tool**，查看执行状态、耗时和完整返回结果。
5. 带 UI 的工具执行成功后，会读取对应 HTML，并在 **Card preview** 中加载卡片。

卡片预览顶部显示 Local 或 Module Federation 加载模式及资源 URI。MF 工具执行后还会显示服务端实际返回的 manifest 地址，便于确认当前连接的项目和资源来源。

Inspector 页面通过真实的 MCP endpoint 调用工具，卡片通过官方 AppBridge 完成握手和数据传递。卡片发起的工具调用也会转发给该 endpoint，因此任务管理等交互可以继续操作。执行会产生工具本身的业务效果。

参数 JSON、HTTP、MCP 和卡片通信错误会显示在错误区域。工具返回的 `isError` 会显示为工具错误，不加载新卡片。浏览器中的脚本加载错误和 CSP 错误仍需查看开发者工具控制台。

## 只预览本地 UI

启用 `mcpAppsPlugin({ mode: 'ui-only' })` 时，Inspector 页面默认选择 **Simulate local UI**。

选择本地视图，在 **Arguments (JSON)** 中输入工具参数，在 **View props (JSON)** 中输入服务端原本会返回的 `viewProps`，点击 **Preview card**。

模拟模式无需 MCP Server，只验证卡片渲染和宿主握手。它不执行业务 handler，也不支持卡片继续调用服务端工具。需要完整验证时，取消模拟模式，填写已有 Server 的 MCP endpoint 并连接。跨域 endpoint 需要服务端允许Inspector 页面的 Origin 并配置 CORS。

模拟列表包含本地构建的组件视图，MF 和显式 HTML 视图通过真实 endpoint 调试。

## 关闭Inspector 页面

```ts
mcpAppsPlugin({ inspector: false });
```

Inspector 宿主用于本地验证，不等同于目标产品宿主。发布前仍需在目标宿主验证卡片、网络权限和交互兼容性。

## 请求日志

右侧的 **Request logs** 显示当前页面最近 100 次 MCP 请求，包括初始化、工具发现、工具调用和资源读取。卡片内发起的工具调用也会记录，并标记为 Card → Server。

每条日志展示时间、方法、状态和耗时，展开后可查看 endpoint、请求参数及响应结果。可以筛选 Tool calls、Resource reads 或 Errors，点击 Clear 清空。日志只保留在当前页面内存中，刷新后清除。较大的响应会截断显示。

## 标准宿主能力

Inspector 在本机独立端口运行跨源 sandbox proxy。HTML 在第二层 iframe 中加载，服务端响应头根据资源 CSP 限制网络、脚本、样式、字体、嵌套框架和 base URI。资源内容上的 `_meta.ui` 优先于资源列表元数据，同时支持 `text` 和 base64 `blob` HTML。预览当前拒绝摄像头、麦克风、定位和剪贴板权限。

sandbox 仅监听 `127.0.0.1`，因此需要在运行开发服务器的同一台电脑打开 Inspector。它不会在生产构建中启动。开发用 HMR WebSocket 也必须符合 CSP，未声明的连接会被拦截。

卡片可以更新模型上下文、发送消息和日志、读取服务端资源、打开 HTTP 或 HTTPS 链接、下载资源，以及请求展示模式或关闭。上下文覆盖上一次更新，消息与日志显示在页面内，Inspector 不会触发真实模型回复。打开链接和下载会要求用户确认。

**App-provided tools** 可以刷新卡片注册的工具列表并执行工具。卡片工具在 iframe 销毁后失效。工具调用转发会检查 `visibility`，拒绝卡片调用仅对模型开放的服务端工具。替换或关闭预览前会发送 `ui/resource-teardown`，运行中的请求可通过 **Cancel** 取消。