@lark-apaas/coding-steering 0.1.32-dev.88fb097 → 0.1.32-dev.a04167f

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/package.json +1 -1
  2. package/steering/nestjs-react-fullstack/skills_common/mcp-guide/SKILL.md +4 -4
  3. package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/client-onboarding.md +5 -13
  4. package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/debugging.md +9 -9
  5. package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/mcp-apps.md +3 -3
  6. package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/tool-authoring.md +3 -3
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lark-apaas/coding-steering",
3
- "version": "0.1.32-dev.88fb097",
3
+ "version": "0.1.32-dev.a04167f",
4
4
  "description": "Stack-specific steering content for miaoda-coding templates",
5
5
  "type": "module",
6
6
  "files": [
package/steering/nestjs-react-fullstack/skills_common/mcp-guide/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: mcp-guide
3
- description: "Use when 用户要把应用能力开放给外部 Agent / 工作伙伴 / MCP 客户端调用，新增或修改 MCP 工具，给工具结果加界面（MCP Apps / ui:// 资源），维护应用 Skill（server/mcp/skills/<name>/SKILL.md，SDK 注册为 MCP Prompt），要在开发态核对、调用、调试 MCP 工具，或要把本应用的 MCP 接到自己的 Agent 客户端上使用。触发词：MCP, MCP Server, MCP 工具, MCP Apps, ui://, @McpTools, @McpTool, @McpUiResource, McpToolError, readMcpUiTemplate, tools/list, tools/call, resources/read, prompts/list, prompts/get, mcp_call, 开放给 Agent, 工作伙伴调用, Agent 调用应用, 应用 Skill, server/mcp, server/mcp/ui, server/mcp/skills, 接入 MCP, 连接 MCP, 怎么用这个 MCP, MCP 客户端, Claude Code, Codex, mcp add, mcp login, config.toml, X-Mcp-Token, MCP 凭证, 可用范围, 连不上。不负责 HTTP 对外开放接口（走 openapi-guide）、自动化触发器（走 trigger-guide）。"
3
+ description: "Use when 用户要把应用能力开放给外部 Agent / 工作伙伴 / MCP 客户端调用，新增或修改 MCP 工具，给工具结果加界面（MCP Apps / ui:// 资源），维护应用 Skill（server/mcp/skills/<name>/SKILL.md，SDK 注册为 MCP Prompt），要在开发态核对、调用、调试 MCP 工具，或要把本应用的 MCP 接到自己的 Agent 客户端上使用。触发词：MCP, MCP Server, MCP 工具, MCP Apps, ui://, @McpTools, @McpTool, @McpUiResource, McpToolError, readMcpUiTemplate, tools/list, tools/call, resources/read, prompts/list, prompts/get, mcp_inspect, 开放给 Agent, 工作伙伴调用, Agent 调用应用, 应用 Skill, server/mcp, server/mcp/ui, server/mcp/skills, 接入 MCP, 连接 MCP, 怎么用这个 MCP, MCP 客户端, Claude Code, Codex, mcp add, mcp login, config.toml, X-Mcp-Token, MCP 凭证, 可用范围, 连不上。不负责 HTTP 对外开放接口（走 openapi-guide）、自动化触发器（走 trigger-guide）。"
4
4
  steering: true
5
5
  steering-topic: mcp_guide
6
6
  match-template-name: nestjs-react-fullstack
@@ -41,10 +41,10 @@ ls -d node_modules/@lark-apaas/nestjs-mcp node_modules/@lark-apaas/coding-preset
41
41
  |---|---|
42
42
  | 新增 / 修改工具、开通 MCP、维护应用 Skill | `$SKILL_DIR/references/tool-authoring.md` |
43
43
  | 给工具结果加界面、改界面、界面与工具联动 | `$SKILL_DIR/references/mcp-apps.md` |
44
- | 用 `mcp_call` 核对与调用、按错误定位、本地模式调试 | `$SKILL_DIR/references/debugging.md` |
44
+ | 用 `mcp_inspect` 核对与调用、按错误定位、本地模式调试 | `$SKILL_DIR/references/debugging.md` |
45
45
  | 用户要在自己的 Agent（Claude Code / Codex / 其它客户端）里连本应用的 MCP | `$SKILL_DIR/references/client-onboarding.md` |
46
46
 
47
- 前三类是改代码，改完等 dev server 重启（定义有问题会在启动日志里报），再按 `$SKILL_DIR/references/debugging.md` 的回路用 `mcp_call` 验证。`mcp_call` 报「当前运行环境不支持」是本地 CLI 宿主，走该文件的本地模式。向用户汇报用业务表述（「找到 4 个演示航班」），不贴 JSON。
47
+ 前三类是改代码，改完等 dev server 重启（定义有问题会在启动日志里报），再按 `$SKILL_DIR/references/debugging.md` 的回路用 `mcp_inspect` 验证。`mcp_inspect` 报「当前运行环境不支持」是本地 CLI 宿主，走该文件的本地模式。向用户汇报用业务表述（「找到 4 个演示航班」），不贴 JSON。
48
48
 
49
49
  ## 不变量
50
50
 
@@ -52,7 +52,7 @@ ls -d node_modules/@lark-apaas/nestjs-mcp node_modules/@lark-apaas/coding-preset
52
52
  2. schema 用 zod，提成常量放类上方；方法签名固定 `(input: Infer<typeof In>, ctx: McpContext)`，返回 `McpToolResult<typeof Out>`。签名写错在 `npm run type:check:server` 暴露。
53
53
  3. `description` 面向模型：用途、何时调用、参数来源、返回什么、失败怎样。每个 zod 字段 `.describe()`。消费方 Agent 只靠这些选工具、填参数。
54
54
  4. 四项 `annotations` 显式写出。只读工具必须 `readOnlyHint: true`：缺省会被当成可能写数据，调试时每次都要 `safe: true`，消费方也会额外确认。
55
- 5. 声明了 `outputSchema` 就返回匹配的 `structuredContent`，对不上时 `mcp_call` 报「输出与其声明的 outputSchema 不符」；列表工具入参带 `limit`（默认不超过 20）与 `cursor`；写操作的幂等由 Service 保证，不引入幂等键字段。
55
+ 5. 声明了 `outputSchema` 就返回匹配的 `structuredContent`，对不上时 `mcp_inspect` 报「输出与其声明的 outputSchema 不符」；列表工具入参带 `limit`（默认不超过 20）与 `cursor`；写操作的幂等由 Service 保证，不引入幂等键字段。
56
56
  6. 返回值按消费方够用来裁：`structuredContent` 只放它推理或界面渲染要用的字段。SDK 不截断，返回多少对方就吃多少，详见 `$SKILL_DIR/references/tool-authoring.md` 的「返回体积」。
57
57
  7. 业务失败抛 `McpToolError(message, { code })`，Agent 原样收到；`message` 连下一步一起写（「订单不存在，用 order_search 按客户名重查一个有效 ID」），只陈述现象会让对方原样重试或直接放弃。其他异常只落日志、返回通用提示，Agent 看不到原因。
58
58
  8. 身份只从 `ctx.user` 读；权限与行级过滤留在 Service。工具类作为业务模块 provider 注册，单例——请求态（当前用户、本次入参、游标）只放方法内的局部变量，写进类字段会在并发请求间串号。
package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/client-onboarding.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # 接入：把本应用的 MCP 连到外部客户端
2
2
 
3
- 适用于「应用已经有 MCP 工具，用户要在自己的 Agent（Claude Code / Codex / 其它 MCP 客户端）里调用它」。开发态自己验工具走 `debugging.md` 的 `mcp_call`，与本文无关。
3
+ 适用于「应用已经有 MCP 工具，用户要在自己的 Agent（Claude Code / Codex / 其它 MCP 客户端）里调用它」。开发态自己验工具走 `debugging.md` 的 `mcp_inspect`，与本文无关。
4
4
 
5
5
  **产出是一条用户复制即可执行的命令，不是操作说明。**连接地址和凭证都由你查出来填好，不要让用户自己去界面上找。
6
6
 
@@ -34,25 +34,18 @@ lark-cli apps +mcp-get --app-id "$app_id" --include-secret
34
34
  **Claude Code**
35
35
 
36
36
  ```bash
37
- claude mcp add --transport http <名字> <连接地址> --header "X-Mcp-Token: <凭证>" --header "x-tt-env: boe_miaoda_mcp"
37
+ claude mcp add --transport http <名字> <连接地址> --header "X-Mcp-Token: <凭证>"
38
38
  claude mcp login <名字>
39
39
  ```
40
40
 
41
- **Codex** — 编辑 `~/.codex/config.toml`
42
-
43
- ```toml
44
- [mcp_servers.<名字>]
45
- url = "<连接地址>"
46
- http_headers = { "X-Mcp-Token" = "<凭证>", "x-tt-env" = "boe_miaoda_mcp" }
47
- ```
41
+ **Codex**
48
42
 
49
43
  ```bash
44
+ codex mcp add <名字> --url "<连接地址>?x-mcp-token=<凭证>"
50
45
  codex mcp login <名字>
51
46
  ```
52
47
 
53
- Codex 侧同名 table 在 TOML 里出现两次是解析错误，已有同名配置要整块替换而不是追加；不要填 `bearer_token_env_var`，它会走静态 token 分支把 OAuth 跳过去。
54
-
55
- 两份模板里的 `x-tt-env` 照原样带上，不要改它的值，也不要就它询问用户。
48
+ `codex mcp add` 没有传请求头的参数，凭证走 query 参数。不要用 `--bearer-token-env-var`，它会走静态 token 分支把 OAuth 跳过去。
56
49
 
57
50
  ## 为什么是两条命令
58
51
 
@@ -80,7 +73,6 @@ Codex 侧同名 table 在 TOML 里出现两次是解析错误，已有同名配
80
73
  | 401，无 reason | 凭证复制不全，或配的是预览态凭证 | 重新 `+mcp-get --include-secret` 取一次，整段替换 |
81
74
  | 403 `user is not in the visible scope of this app` | 不在可用范围，或授权账号不属于应用租户 | 前者找负责人放开范围；后者换应用租户内的账号授权 |
82
75
  | 404 | 应用没启用 MCP；或零工具零资源无应用 Skill（SDK 此时也返回 404） | 后者是正常状态不是故障，先确认本应用确实注册了工具 |
83
- | 连接超时 / 长时间挂起 | 多为泳道头指向了不存在或未部署的泳道 | 去掉 `x-tt-env` 再试一次可快速定位 |
84
76
  | POST 被拒，CSRF 相关 | 旧模板应用对 POST 有 CSRF 双提交校验 | 平台侧已知未收口项，告知用户，不在客户端侧拼 cookie 绕 |
85
77
 
86
78
  ## 凭证纪律
package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/debugging.md CHANGED
@@ -1,8 +1,8 @@
1
- # 调试：mcp_call、错误定位、本地模式
1
+ # 调试：mcp_inspect、错误定位、本地模式
2
2
 
3
- 本文说的「沙箱」= 工具清单里有 `mcp_call` 的环境（妙搭云端 code-agent）；「本地模式」= 没有 `mcp_call`、在开发者本机跑 `npm run dev` 的环境。先看自己有哪个，再读对应部分。
3
+ 本文说的「沙箱」= 工具清单里有 `mcp_inspect` 的环境（妙搭云端 code-agent）；「本地模式」= 没有 `mcp_inspect`、在开发者本机跑 `npm run dev` 的环境。先看自己有哪个，再读对应部分。
4
4
 
5
- ## mcp_call
5
+ ## mcp_inspect
6
6
 
7
7
  云端沙箱里的开发态 MCP 调试工具。它经 MCP 网关连当前应用的开发态 MCP Server，以当前用户身份发起，与预览页里操作应用的身份一致。
8
8
 
@@ -17,7 +17,7 @@
17
17
  - 同一工具连续失败 4 次熔断 60s：先改代码或入参，不是等。`requires_safe`、`tool_not_found`、`aborted` 不计入熔断。
18
18
  - 失败或 `isError: true` 时结果尾部附 Trace-ID 对应的 `server.log` / `trace.log` 片段。
19
19
 
20
- **目录接口**：`GET http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/__innerapi__/mcp/manifest`（`CLIENT_DEV_PORT` 默认 8080；`CLIENT_BASE_PATH` 沙箱里是平台下发的 `/app/<appId>`，漏了前缀拿不到 JSON，取值以 `.env.local` 或 dev server 启动日志为准）返回 `tools` / `resources` / `prompts` / `skills[]`（含 frontmatter 的完整正文）与源码定位，不要求身份，有无 `mcp_call` 都能 curl。应用 Skill 是 Prompt 不是资源，`mcp_call` 的三个动作都碰不到它，核对它只走这里。
20
+ **目录接口**：`GET http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/__innerapi__/mcp/manifest`（`CLIENT_DEV_PORT` 默认 8080；`CLIENT_BASE_PATH` 沙箱里是平台下发的 `/app/<appId>`，漏了前缀拿不到 JSON，取值以 `.env.local` 或 dev server 启动日志为准）返回 `tools` / `resources` / `prompts` / `skills[]`（含 frontmatter 的完整正文）与源码定位，不要求身份，有无 `mcp_inspect` 都能 curl。应用 Skill 是 Prompt 不是资源，`mcp_inspect` 的三个动作都碰不到它，核对它只走这里。
21
21
 
22
22
  ## 回路
23
23
 
@@ -39,7 +39,7 @@
39
39
  | 启动日志「MCP 定义校验失败」 | 工具名不合法 / 重名、资源 URI 不以 `ui://` 开头 / 重名、`ui.resourceUri` 找不到 `@McpUiResource()`、同一方法同时标两个装饰器 | 按日志逐条列的问题逐个修 |
40
40
  | `tool_not_found` | 名字没带 prefix，或用了 `title` | 用 `list_tools` 里的 name |
41
41
  | `requires_safe` | 见上文 `safe` | 只读工具补注解；写工具按回路第 5 步——能清掉痕迹才 `safe: true`，否则只验错误分支 |
42
- | `isError` + `code: MCP_USER_REQUIRED`（`prompts/get` / `resources/read` 则是 JSON-RPC error） | 请求没带用户身份：有 `mcp_call` 的环境里 curl 直连 dev server / NestJS 端口就是这样 | 无身份的 curl 只做 `tools/list`、`prompts/list`、`resources/list` 与目录接口；`tools/call` / `resources/read` 走 `mcp_call`，Prompt 正文看目录接口的 `skills[].content`。不改 `requireUser`、不拼身份头 |
42
+ | `isError` + `code: MCP_USER_REQUIRED`（`prompts/get` / `resources/read` 则是 JSON-RPC error） | 请求没带用户身份：有 `mcp_inspect` 的环境里 curl 直连 dev server / NestJS 端口就是这样 | 无身份的 curl 只做 `tools/list`、`prompts/list`、`resources/list` 与目录接口；`tools/call` / `resources/read` 走 `mcp_inspect`，Prompt 正文看目录接口的 `skills[].content`。不改 `requireUser`、不拼身份头 |
43
43
  | `isError` + 业务 `code` | 工具按设计抛了 `McpToolError` | 对照 `description` 检查是否预告了该 code；入参是否真的该触发 |
44
44
  | `isError` + 通用失败提示 | 方法抛了非 `McpToolError` 的异常 | 读结果尾部 Trace-ID 日志定位；该异常若是可预期的业务失败，改抛 `McpToolError` |
45
45
  | zod 校验错误 | 入参不符 inputSchema | 对照 `list_tools` 里的 schema 改 `arguments`；schema 本身不合理就改源码 |
@@ -49,16 +49,16 @@
49
49
  | `jsonrpc_error` + `data.code: MCP_APP_REVISION_MISMATCH` | 调用方带的应用修订与当前产物不一致（改代码、改界面、改应用 Skill、dev server 重启都会变），**本次业务未执行** | 重新 `list_tools` 取最新清单再调；不要原样重试，也不要把这当业务失败去改工具代码 |
50
50
  | `jsonrpc_error` + `data.code: MCP_APP_REVISION_UNAVAILABLE` | 产物是旧版构建、不带修订，而调用方带了预期修订 | 同步新版构建脚本后重新发布；在那之前不要启用依赖修订的绑定 |
51
51
  | 「已连续 4 次调用失败，已暂停对它的重复调用」 | 同一工具连续失败 4 次熔断 | 先修实现或入参，60s 后再验 |
52
- | 「当前运行环境不支持开发态 MCP 调试」 | 本地 CLI 宿主没有 `mcp_call` 后端 | 走下节本地模式 |
52
+ | 「当前运行环境不支持开发态 MCP 调试」 | 本地 CLI 宿主没有 `mcp_inspect` 后端 | 走下节本地模式 |
53
53
  | `read_resource` 报「读取 MCP Apps 界面产物失败」 | `dist/mcp-ui/<entry>.html` 不存在 | 入口名对齐 `readMcpUiTemplate('<entry>')`；确认 `server/mcp/ui/<entry>/index.html` 存在；看 `[mcp-ui]` 日志是否构建失败 |
54
54
  | dev server 日志 `[mcp-ui] 构建失败：MCP UI 不能引用应用或服务端代码 / Node.js 模块` | 界面 import 了 `client/`、`server/` 的业务代码或 Node 内置模块；HTML `src`、CSS `url()` 指到界面目录外也算 | 把依赖挪进 `server/mcp/ui/` 或 `shared/`；不改预设配置 |
55
- | `mcp_call` 任一动作 `http_error` 500、目录接口 500，server 日志有「处理 MCP 请求失败」、栈首行是「MCP Skill …」 | 某份 `server/mcp/skills/*/SKILL.md` frontmatter 不合法：缺 frontmatter、`name` 与目录名不等、`description` 空、重名、超限 | 按日志文案修 frontmatter |
55
+ | `mcp_inspect` 任一动作 `http_error` 500、目录接口 500，server 日志有「处理 MCP 请求失败」、栈首行是「MCP Skill …」 | 某份 `server/mcp/skills/*/SKILL.md` frontmatter 不合法：缺 frontmatter、`name` 与目录名不等、`description` 空、重名、超限 | 按日志文案修 frontmatter |
56
56
 
57
57
  同一失败不原样重试。改完代码再验，每轮只改一个变量。
58
58
 
59
- ## 本地模式（工具清单里没有 `mcp_call` 时才适用）
59
+ ## 本地模式（工具清单里没有 `mcp_inspect` 时才适用）
60
60
 
61
- 本地开发（`MIAODA_LOCAL_DEV=1`，`npm run dev` 走 `dev-local.js`）没有 `mcp_call`，MCP 客户端是你自己或 IDE 里的 Agent。
61
+ 本地开发（`MIAODA_LOCAL_DEV=1`，`npm run dev` 走 `dev-local.js`）没有 `mcp_inspect`，MCP 客户端是你自己或 IDE 里的 Agent。
62
62
 
63
63
  - 带身份的入口只有 dev server：`http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/__innerapi__/mcp`（`CLIENT_BASE_PATH` 以 `.env.local` 为准，`+env-pull` 拉下来的是 `/app/<appId>`）。dev server 代理把 `+env-pull` 拉到的 `SUDA_WEBUSER` 注入为身份头，工具里的 `ctx.user` 就是开发者本人。直连 NestJS 端口没有身份，会撞 `MCP_USER_REQUIRED`。
64
64
  - 标准 MCP 客户端配置 Streamable HTTP、URL 填上面地址即可连接。
package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/mcp-apps.md CHANGED
@@ -87,7 +87,7 @@ export class OrderMcpTools {
87
87
  ```
88
88
 
89
89
  - `uri` 必须以 `ui://` 开头，全应用唯一；`ui.resourceUri` 找不到对应 `@McpUiResource()` 时应用启动会报错。
90
- - `visibility` 默认 `['model', 'app']`。只给界面用的取数 / 刷新工具写 `['app']`，避免污染模型的工具清单。隐藏由宿主做，server 不过滤：`mcp_call` 的 `list_tools` 仍会列出它，`_meta.ui.visibility` 为 `['app']` 即正确，不要因为「还在清单里」去改代码。
90
+ - `visibility` 默认 `['model', 'app']`。只给界面用的取数 / 刷新工具写 `['app']`，避免污染模型的工具清单。隐藏由宿主做，server 不过滤：`mcp_inspect` 的 `list_tools` 仍会列出它，`_meta.ui.visibility` 为 `['app']` 即正确，不要因为「还在清单里」去改代码。
91
91
  - 绑了界面就在 `description` 里说出来（「结果以可交互的订单列表展示，可在界面里展开详情、取消订单」）。模型只看 `description` 选工具，不写它可能改调别的工具或自己拼 ID。
92
92
  - 一个工具既返回 `structuredContent` 又绑界面是常态；模型还需要纯数据继续推理时，拆成「取数工具（无 ui）」+「展示工具（绑 ui）」。
93
93
  - 资源读取沿用 `requireUser`：无身份的 `resources/read` 会被拒。
@@ -192,6 +192,6 @@ await app.connect();
192
192
 
193
193
  ## 调试
194
194
 
195
- - `mcp_call` `read_resource` 读 `ui://…`：成功返回 `text/html;profile=mcp-app` 与正文开头；报「读取 MCP Apps 界面产物失败」→ `dist/mcp-ui/<entry>.html` 不存在：入口名与 `readMcpUiTemplate('<entry>')` 不一致、`server/mcp/ui/<entry>/index.html` 缺失、或 dev server 还没重建，看 dev server 日志里 `[mcp-ui]` 前缀的行。构建失败行里出现「MCP UI 不能引用…」是依赖越界，按上文边界规则改 import，不改预设。
196
- - 界面逻辑用 `mcp_call` 看不到；先用 `call` 确认 `structuredContent` 形状正确，再在预览里看渲染。宿主渲染失败时保留工具结果，只重试界面。
195
+ - `mcp_inspect` `read_resource` 读 `ui://…`：成功返回 `text/html;profile=mcp-app` 与正文开头；报「读取 MCP Apps 界面产物失败」→ `dist/mcp-ui/<entry>.html` 不存在：入口名与 `readMcpUiTemplate('<entry>')` 不一致、`server/mcp/ui/<entry>/index.html` 缺失、或 dev server 还没重建，看 dev server 日志里 `[mcp-ui]` 前缀的行。构建失败行里出现「MCP UI 不能引用…」是依赖越界，按上文边界规则改 import，不改预设。
196
+ - 界面逻辑用 `mcp_inspect` 看不到；先用 `call` 确认 `structuredContent` 形状正确，再在预览里看渲染。宿主渲染失败时保留工具结果，只重试界面。
197
197
  - 界面里调 `callServerTool` 失败，错误也走 server 日志：按 Trace-ID 查。
package/steering/nestjs-react-fullstack/skills_common/mcp-guide/references/tool-authoring.md CHANGED
@@ -146,7 +146,7 @@ export class OrderModule {}
146
146
 
147
147
  ## 返回体积
148
148
 
149
- SDK 不截断，返回多少消费方 Agent 就吃多少，超了是它的上下文被挤掉。`mcp_call` 里看到的截断与落盘是调试通道的显示预算，与工具该返回多少无关。
149
+ SDK 不截断，返回多少消费方 Agent 就吃多少，超了是它的上下文被挤掉。`mcp_inspect` 里看到的截断与落盘是调试通道的显示预算，与工具该返回多少无关。
150
150
 
151
151
  - `structuredContent` 只放对方推理或界面渲染要用的字段。Service 查出来的整行记录、外键、审计字段先挑一遍再返回。
152
152
  - 列表工具 `limit` 默认不超过 20、上限写进 zod（`.max(50)`）；要更多靠 `cursor` 翻页，不靠调大 `limit`。
@@ -163,7 +163,7 @@ return {
163
163
  };
164
164
  ```
165
165
 
166
- - 图片、附件、长文本用 `content` 里的 `resource_link` 给指针，不内联进结果。`mcp_call` 只渲染文本块，这类块在调试结果里不显示，别据此以为工具什么都没返回。
166
+ - 图片、附件、长文本用 `content` 里的 `resource_link` 给指针，不内联进结果。`mcp_inspect` 只渲染文本块，这类块在调试结果里不显示，别据此以为工具什么都没返回。
167
167
 
168
168
  ## McpContext
169
169
 
@@ -244,6 +244,6 @@ PlatformModule.forRoot({
244
244
  // 关闭端点：PlatformModule.forRoot({ mcp: false })
245
245
  ```
246
246
 
247
- **`serverName` 首次开通时就设上。** `initialize` 把它返回给连上来的外部 Agent，`mcp_call` 的 `list_tools` 也显示它；不设则是 `miaoda-app`，谁看都不知道是哪个应用。取材于本 MCP 做什么（差旅审批 → `travel-approval`，库存查询 → `inventory`），小写字母 + 数字 + `-`／`_`，两三个词以内。
247
+ **`serverName` 首次开通时就设上。** `initialize` 把它返回给连上来的外部 Agent，`mcp_inspect` 的 `list_tools` 也显示它；不设则是 `miaoda-app`，谁看都不知道是哪个应用。取材于本 MCP 做什么（差旅审批 → `travel-approval`，库存查询 → `inventory`），小写字母 + 数字 + `-`／`_`，两三个词以内。
248
248
 
249
249
  其余项一般不动。`requireUser` 保持默认 `true`。零工具、零资源、无应用 Skill 时端点返回 404，这是正常状态不是故障。