1. 选择宿主配置
如果渲染 MCP Apps UI，使用 WebUI Profile。如果宿主是由专门 Agent 和外部配置的 LLM 组成的编排层，则使用 Agent Profile。
快速开始
MCPlet 宿主与工具开发者的第一步
本指南将 MCPlet v202603-03 压缩为一条实现路径：选择合适的宿主配置、正确分类工具、公开代码优先的元数据，并在可能产生副作用的操作中应用更严格的强制措施。
实现路径
- 选择您的宿主是 WebUI Profile 还是 Agent Profile。这决定了 MCP Apps 渲染是否是运行时的一部分，以及如何实现确认流程。
- 将每个工具分类为 read、prepare 或 action。这不仅仅是文档说明，而是安全模型的一部分。
- 在 _meta 中注册代码优先的元数据，包括 mcpletType、visibility，以及可选的 ui、auth 和 pool 字段。
- 公开工具结果模式 URI，以便宿主可以验证结构化结果，下游消费者可以安全地推断输出内容。
- 当模型可见的 action 可能触发不可逆副作用时，要求严格的 passkey 强制执行。
如果只记住一条规则：永远不要将 MCPlet 视为 MCP 的替代品。MCP 是协议层，MCPlet 是将工具行为收窄为更安全、可审查单元的规约层。
2. 分类工具
安全检索选 read，分阶段验证选 prepare，需要更严格控制的不可逆副作用选 action。
3. 公开代码优先的元数据
至少声明 _meta.mcpletType 和 _meta.visibility。在适用时添加结果模式 URI、UI 元数据、auth 元数据和 pool。
4. 保护模型可见的 action
如果某个 action 对模型可见，要求明确的拦截和强确认，最好使用严格的 Passkey 强制执行。
MCP、MCP Apps 与 MCPlet 概览
| 层次 | 主要职责 | 提供的内容 | 不提供的内容 |
|---|---|---|---|
| MCP | 协议 | 工具和资源的传输、发现和调用语义。 | 意图建模、操作安全策略或工具分类规范。 |
| MCP Apps | UI 集成 | 宿主视图渲染、iframe 生命周期和应用桥接行为。 | 业务意图边界、元数据安全规则或认证规约。 |
| MCPlet | 规约配置 | 单意图单元、read/prepare/action 分类、可见性约束、认证要求和宿主管理的安全边界。 | MCP 传输、通用运行时行为或强制性前端框架。 |
最小代码优先元数据示例
此示例展示了将工具映射到 MCPlet 时大多数实现应首先考虑的字段。
{
"_meta": {
"mcpletType": "prepare",
"visibility": ["model", "app"],
"mcpletToolResultSchemaUri": "mcplet://tool-result-schema/check_order",
"ui": {
"resourceUri": "ui://orders/check.html",
"displayMode": "inline"
}
}
}
对于不可逆操作，将分类切换为 action 并添加具有更严格强制执行的 _meta.auth。
何时使用 MCPlet，何时不使用
使用 MCPlet 的场景
- 您希望每个工具只有一个可审查的业务意图。
- 您需要宿主强制执行清晰的模型与应用边界。
- 您希望在 MCP 之上建立代码优先的元数据契约。
不使用 MCPlet 的场景
- 工具覆盖面有意设计为宽泛且多用途。
- 您在寻找替代协议，而非规约配置。
- 宿主无法管理状态、拦截或安全策略。
需要许可上下文？请查看知识产权声明。