@lark-apaas/nestjs-mcp 0.2.0-alpha.0 → 0.2.0-alpha.1

package/README.md

@@ -3,7 +3,7 @@
 为妙搭全栈应用（NestJS）提供 MCP Server 能力：用装饰器把业务方法开放为 MCP 工具，SDK 负责协议、装配、入参校验、身份读取与清单导出，并通过标准 Skills 扩展发现应用工作流，将交互界面暴露为 MCP Apps 资源。
 
 - 端点：`POST /__innerapi__/mcp`（Streamable HTTP 无状态模式，不含 SSE；支持 2026-07-28 现代协议，兼容 2025-11-25 及既有旧版客户端；运行环境 Node.js 20+）。应用设置 `CLIENT_BASE_PATH` 时完整路径为 `${CLIENT_BASE_PATH}/__innerapi__/mcp`
-- 底层：现代协议使用 `@modelcontextprotocol/server` / `@modelcontextprotocol/node` v2，旧协议保留 `@modelcontextprotocol/sdk` v1；`@modelcontextprotocol/ext-apps`（MCP Apps，`ui://` 单文件 HTML 资源）
+- 底层：使用 `@modelcontextprotocol/server` / `@modelcontextprotocol/node` v2；`@modelcontextprotocol/ext-apps`（MCP Apps，`ui://` 单文件 HTML 资源）
 - 身份：网关注入 `x-larkgw-suda-webuser`，`UserContextMiddleware` 解析到 `req.userContext`，工具通过 `ctx.user` 读取
 - 装配：已被 `PlatformModule.forRoot()` 自动引入，业务工程 import `@lark-apaas/fullstack-nestjs-core` 即获得
 
@@ -107,7 +107,7 @@ description: 查询订单当前状态并向用户说明处理进度
 
 以上仍是同一个 HTTP 端点的 JSON-RPC 方法，不增加 `/mcp/skills/get` 子路由。2026-07-28 请求的 `_meta` 和 HTTP 协议头应由支持该版本的 MCP 客户端生成；官方 TypeScript v2 客户端需启用 `versionNegotiation: { mode: 'auto' }`。SDK 尚无专用 Skills 方法时，使用其通用 `client.request()` 并提供结果 schema。`skills/list/get` 的线协议结果带 `resultType: "complete"`、`ttlMs: 0`、`cacheScope: "private"`；客户端 SDK 可能在解码时移除 `resultType`。
 
-旧版客户端仍可通过 `initialize`、`prompts/list`、`prompts/get` 使用既有能力。Prompts 映射进入弃用过渡，新接入使用 Skills 扩展；旧 Prompt 仍返回去掉 YAML 前言的 Markdown 消息。平台 manifest v3 保持原协议，`prompts` / `sources.prompts` 字段保留，不把标准 Skills 响应结构混入面板接口。
+只提供 2026-07-28 Skills 通道，不注册 `prompts/list/get`，不保留旧协议处理分支。平台 manifest v3 按既有面板约定保留 `prompts` / `sources.prompts` 元数据字段；这些字段不代表 MCP Prompt 能力。
 
 规范来源：[Skills 扩展](https://modelcontextprotocol.io/extensions/skills/overview)、[正式规范](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx)。本实现不声明可选的 `directoryRead`。
 
@@ -182,20 +182,19 @@ PlatformModule.forRoot({
 
 | 请求 | 响应 / 默认身份要求 |
 |---|---|
-| `POST /__innerapi__/mcp`：`server/discover`、`skills/list`、`skills/get`、旧版 `initialize`、`tools/list`、`resources/list`、`prompts/list` | HTTP 200，标准 JSON-RPC 响应；SDK 不要求用户身份，列表需按已声明能力调用 |
+| `POST /__innerapi__/mcp`：`server/discover`、`skills/list`、`skills/get`、`tools/list`、`resources/list` | HTTP 200，标准 JSON-RPC 响应；SDK 不要求用户身份，列表需按已声明能力调用 |
 | 同端点 `tools/call` | 要求 `ctx.user.userId`；缺失返回 `isError: true`，错误码 `MCP_USER_REQUIRED` 在结果元数据中 |
-| 同端点 `resources/read`、旧版 `prompts/get` | 要求用户身份；缺失返回 JSON-RPC error |
-| 同端点 `notifications/initialized` | HTTP 202，空响应体 |
+| 同端点 `resources/read` | 要求用户身份；缺失返回 JSON-RPC error |
 | `GET` / `DELETE` MCP 端点 | HTTP 405，`Allow: POST`；不提供 SSE 流 |
 | POST 时工具、UI 资源和 Skill 均为空 | HTTP 404 |
 | POST 的 `Accept` 未同时包含 `application/json` 和 `text/event-stream` | HTTP 406；标准客户端会设置这两个值，即使服务端使用 JSON 响应 |
 | `GET /__innerapi__/mcp/manifest` | 平台目录接口，见下文；不需要 MCP 握手 |
 
-`tools/list`、`resources/list` 仅在注册对应能力时可用，否则返回 JSON-RPC `-32601 Method not found`。客户端应根据 `server/discover` 或旧版 `initialize` 的 `capabilities` 调用；`prompts/list` 在服务可用时支持返回空数组。
+客户端应根据 `server/discover` 的 `capabilities` 调用；`skills/list` 和 `resources/list` 支持空数组，`tools/list` 仅在注册工具时可用。
 
 平台负责凭证鉴权和可信身份注入；SDK 检查用户身份是否存在，并交给业务 Service 执行权限校验。工具类使用单例 provider，不承诺工具方法上的 Nest Guard / Pipe / Interceptor 自动执行，也不能依赖 HTTP Controller 上的权限装饰器。`requireUser: false` 可关闭 SDK 的身份存在性检查，不会关闭网关鉴权。
 
-`initialize.result.protocolVersion` 是 MCP 协商版本，`serverInfo.version` 是模块配置的服务实现版本；下文的 `version: 3` 是平台清单结构版本。三者用途不同，均不能直接当作应用源码或 UI 内容更新标识。
+`2026-07-28` 是 MCP 协议版本，响应 `_meta["io.modelcontextprotocol/serverInfo"].version` 是模块配置的服务实现版本；下文的 `version: 3` 是平台清单结构版本。三者用途不同，均不能直接当作应用源码或 UI 内容更新标识。
 
 ## 导出
 
@@ -209,10 +208,10 @@ PlatformModule.forRoot({
 
 | 位置 | 含义 |
 |---|---|
-| 成功响应 `result._meta["com.feishu.miaoda/appRevision"]` | 当前请求使用的修订；包括发现、列表、工具、资源、Skill 元数据和旧 Prompt 响应 |
-| `tools/call`、`resources/read`、`skills/get`、旧版 `prompts/get` 的 `params._meta` 同名键 | 调用方期望使用的修订，可选；提供时必须为 1–256 字符的字符串 |
+| 成功响应 `result._meta["com.feishu.miaoda/appRevision"]` | 当前请求使用的修订；包括发现、列表、工具、资源、Skill 元数据响应 |
+| `tools/call`、`resources/read`、`skills/get` 的 `params._meta` 同名键 | 调用方期望使用的修订，可选；提供时必须为 1–256 字符的字符串 |
 
-宿主通过 `tools/list`（纯 Skill 应用可用 `skills/list`，旧客户端用 `prompts/list`）刷新修订，将应用/环境/用户、协议版本、修订和资源 URI 纳入缓存键。现代协议的修订额外覆盖附件，旧协议保持已发布的正文修订语义；切换协议后重新获取修订，不跨协议复用。旧 UI 发起请求时由 Host 附加原绑定值，不允许用查询到的新值替换它。示例：
+宿主通过 `tools/list`（纯 Skill 应用可用 `skills/list`）刷新修订，将应用/环境/用户、协议版本、修订和资源 URI 纳入缓存键。修订统一覆盖后端、UI 与 Skill 文件（包含附件）。旧 UI 发起请求时由 Host 附加原绑定值，不允许用查询到的新值替换它。示例：
 
 ```ts
 const key = 'com.feishu.miaoda/appRevision';