/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后,紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

技术基线:Spring Boot 4.0.0+Java 21+Spring AI 2.0.1,无状态/mcp;规范基线SEP-1865(specification/2026-01-26/apps.mdx) 实测环境:本机Windows 11+JDK 21.0.11+Maven 3.9.15,模块15-mcp-apps-deep(端口18095,tagv15发布前打)
引子:界面能点之后,麻烦才开始
系列(五)把界面挂上去了:工具元数据里带_meta.ui.resourceUri,宿主取ui://资源渲染成一块卡片。到那一步为止,界面只是"看"。
真让它能点,会立刻冒出三个入门篇没碰到的问题:表格的筛选、排序、分页谁算;界面上看到的数据和服务端对不上怎么办;界面收到的消息是不是真来自宿主。这篇把三件事做进一张门店库存表,全部本机跑通,贴原始输出。
一、先把规范口径对齐
SEP-1865的文本在2026-01-26版apps.mdx;2026-07-28第五版规范把扩展框架解耦,Apps和Tasks各自独立演进,Apps成了独立正式扩展。本篇按解耦后的口径写,不沿用发布前的SEP草稿形态,长流程任务也不在范围。基础概念(_meta.ui.resourceUri、沙箱iframe、postMessage)在系列(五)和MCP Live解读稿(未发布)里讲过,一句带过。
生命周期顺序是resources/list→宿主取resources/read→ui/initialize→initialized→交互(工具结果下发与tools/call)。握手消息名是本篇界面与最小宿主模拟器之间的约定,不同宿主实现可能不同,落地以所用宿主为准。
二、界面能干活,多出来三件事
样例是8条门店库存,界面支持筛选、排序、翻页、勾选批量补货。
| 参数下推 | 界面把keyword/sortBy/page发给工具,服务端算完回structuredContent | 界面不攒全量数据,翻页不会读到脏缓存 |
| 状态同步 | 每次查询回revision,写操作带expectedRevision+idempotencyKey | 旧数据提交要被拒,重复点击不能补两次货 |
| 来源校验 | 握手时记下hostOrigin,之后按e.origin过滤 | iframe里消息不认来源,等于谁都能喂数据 |
比系列(五)多的只有一处元数据:_meta.ui.csp里connectDomains和resourceDomains都留空,表示不申请任何外部域。宿主本来就deny-by-default,不申请最省事。
参数下推有个取舍:界面本地排序最简单,但revision会跟不上分页,界面显示的还是上一页的版本。所以把keyword/sortBy/page交给工具算,界面只渲染。写工具里的两把锁,只留判断:
if(idempotency.containsKey(key)) return DUPLICATE; // 重复提交
if(expectedRevision!=revision) return STALE_REVISION; // 界面数据是旧的
// 放行后补货,revision++,同key落幂等表
幂等键由界面在点击时生成:用户连点和宿主重发复用同一个id,服务端才能认成一次提交。查询工具照旧给structuredContent和content[0].text两份,不支持Apps的宿主拿文本回退。
三、协议层实测:9条断言全过
verify/verify-apps.py打的是真实MCP Server,不是mock。原始输出(节选):
[1] get_inventory_table: resourceUri=ui://inventory-table visibility=['model'] csp={'resourceDomains': [], 'connectDomains': []}
[2] resources/list: mimeType=text/html;profile=mcp-app | tools/call: rows=5 revision=1 文本回退=True
[3] resources/read: 6299 bytes, 外链=0, CSP-meta=True, 握手=True, origin校验=True
[5] approve_restock(revision=1): code=OK revision=2 changed=[('SKU-1001', 42), ('SKU-1003', 37)]
[6] 同幂等键: code=DUPLICATE changed=0 | 旧revision: code=STALE_REVISION changed=0
PASS 9/9
这9条是我脚本里写的断言,只覆盖本文声明的能力,不是协议一致性认证。
approve_restock标了visibility=['app'],tools/list里照样列得出来。宿主可以据此把它藏起来,服务端没有因此多一道门;真正的放行判断得落在鉴权层,本demo没做。
四、没有真实宿主,怎么验握手
没有支持Apps的聊天客户端,协议层能验,界面里的JS行为验不了。我的办法是把resources/read拿到的HTML内联脚本放进Node的vm,写一个最小宿主:发ui/initialize、回工具结果、模拟勾选提交、最后塞一条伪造origin的消息。用的是上一步落盘的真实服务端数据。
[host] -> ui/initialize (origin=https://host.example)
[app] -> initialized {app:inventory-table, capabilities:tools/call+tool-result}
[app] -> tools/call get_inventory_table {"keyword":"","sortBy":"sku","page":1,"pageSize":5}
[app] -> tools/call approve_restock {"skus":"SKU-1001,SKU-1003","expectedRevision":1,"idempotencyKey":"idem-1794126317869-2"}
[app] 已补货2个SKU,revision=2 | revision=2 · 共8条 · 第1页
[app] 忽略外部origin: https://evil.example | revision仍为2
PASS · 共4条消息
origin不硬编码,记在握手那一刻:iframe里拿不到可信的宿主常量,ui/initialize是第一条能确认来源的消息,之后所有回发都限定这个origin。最小宿主只做消息转发和结果回灌,没有实现真实宿主的权限决策,所以它验不了visibility。顺序、参数、锁、origin过滤都能验,iframe里真实渲染什么样,得在真宿主里看。
五、五个坑,都是踩出来的
顺带一个脚本坑:vm里的数组和宿主不同realm,deepStrictEqual直接报Values have same structure but are not reference-equal,改成join(',')比字符串才过。重跑验证脚本前必须重启服务,否则revision和幂等表会带着上一次的状态,第一条断言就过不去。
六、互链与诚实边界
互链(点击跳转):
- → 系列(五)让工具返回一个能点的界面:界面绑定的入门写法,本篇不重复。
- → 系列(六)自建MCP网关:资源没代理,Apps界面会断链。
- → 系列(九)生产化MCP Server的6层安全防护:visibility只是声明,鉴权得落在L2/L3。
- → 篇(十四)全链路追踪(待发布):界面动作的trace可以接进同一根链路。
诚实边界(本机验证≠生产验证):
- 本机已验证:协议层9/9、最小宿主的握手/参数下推/写操作/origin过滤,环境是Windows 11+JDK 21.0.11,单机单进程。
- 待生产验证:真实Apps宿主的iframe渲染与CSP收紧策略、宿主是否真的执行visibility、真实并发下的鉴权与幂等。幂等表和revision都在进程内存里,多实例必须外置。结论只到协议与状态契约成立,不涉及界面视觉效果,也不声称_meta.ui.csp的字段名在所有宿主里通用。
七、自查清单
| _meta.ui.resourceUri+mimeType精确、HTML自包含无外链 | 必做 |
| structuredContent+文本回退 | 必做 |
| 握手记origin、回发限定origin | 必做 |
| 写操作带revision+幂等键 | 必做 |
| 幂等表外置、网关补resources/read代理 | 多实例/走网关必做 |
一句话收尾
界面真能点之后,参数谁算、数据是不是最新的、消息从哪来、重复点击怎么防,都得自己兜。协议层9条断言和最小宿主那4条消息,只能证明契约成立;真宿主里的渲染、鉴权和并发,还得另验。
完整可运行代码在15-mcp-apps-deep(tagv15):Gitee/GitHub,./verify-apps.ps1一键复现,跑通点个star,跑不通提issue。
网硕互联帮助中心





评论前必须登录!
注册