#MCP Apps Inspector

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

#Inspector 工作区

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

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

#根据 inputSchema 填写参数

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

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

{
  "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 页面

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 取消。