diff --git a/docs/README.md b/docs/README.md index f311df3de..779df7a45 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,6 +21,7 @@ - [当前产品与工程约束](./【项目基线】当前产品与工程约束-2026-05-15.md)：现役入口、账号钱包、UI 和后端分层。 - [平台入口与玩法链路](./【玩法创作】平台入口与玩法链路-2026-05-15.md)：只描述现役平台壳与图片画布编辑器链路。 - [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md) +- [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：仅复用现有 External API 的 15 个候选工具、操作映射、说明和参数边界；正式工程设计参考，语义工具尚未实现。 - [External v1 OpenAPI](./openapi/genarrative-external-v1.openapi.json)：公开 HTTP 契约唯一机器可读来源。 ## AI 游戏创作与 Agent Runtime diff --git a/docs/project-memory/shared-memory/document-map.md b/docs/project-memory/shared-memory/document-map.md index c784f822e..fae1f5681 100644 --- a/docs/project-memory/shared-memory/document-map.md +++ b/docs/project-memory/shared-memory/document-map.md @@ -21,6 +21,11 @@ 3. `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs` 与对应 crate README / 源码 4. `docs/openapi/genarrative-external-v1.openapi.json`（涉及 External v1 时） +外部 MCP 语义工具设计： + +1. [外部 OpenAPI 与 API Key 接入方案](../../【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)：现役托管 MCP 与 External API 合同。 +2. [外部 MCP 语义工具说明与参数设计](../../technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：正式工程参考，记录仅复用现有 API 的 15 个候选工具与参数设计；工具尚未实现，不作为已上线能力说明。 + AI 游戏创作 / DirectProject / UI workflow： 1. `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` diff --git a/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md b/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md new file mode 100644 index 000000000..699c0e97c --- /dev/null +++ b/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md @@ -0,0 +1,309 @@ +# 外部 MCP 语义工具说明与参数设计 + +更新时间：`2026-09-23` + +> 文档状态：`current`（正式工程设计参考；语义工具尚未实现，不能据此认定当前服务已提供这些入口）。 +> +> 父规范：[外部 OpenAPI 与 API Key 接入方案](../【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)。 +> +> 当前字段契约：[External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)。本文记录工具划分、说明和参数设计方向；最终英文工具名、完整 JSON Schema、结果投影及兼容发布方式仍需在实现前明确。 + +## 1. 目标与范围 + +在现有 API server 的托管 MCP 层增加按用户任务组织的工具。仅使用现有 External v1 已开放的能力，不直接接入尚未公开的画布功能。 + +工具可以存在自然的功能交集：例如参考图快速变体同时属于生成图片和修改图片，读取画布同时服务于项目查找和布局编辑。不以工具数量或 API 唯一归属为目标，不把不相关任务硬合成一个工具。 + +本文只讨论工具说明、操作选择、关键参数和业务边界。开发者发布页、文档存储与独立发布、CLI 改造不属于本轮范围。本文不改变现有 REST 路由、DTO 和运行行为，也不直接替换现役 MCP 契约。进入工程实现时，按仓库规范驱动流程补齐对应里程碑规范、实现计划和验收条件。 + +## 2. 当前实现与目标调用链 + +当前 [external_mcp.rs](../../server-rs/crates/api-server/src/external_mcp.rs) 从 OpenAPI 自动建立原子工具：工具名由 `operationId` 转为 snake_case；description 优先读取 operation 的 `description`，缺省读取 `summary`，附加 HTTP 方法和路径；参数 schema 来自 OpenAPI。服务级 instructions 提供通用工作流，resources 提供详细说明。 + +新工具拟继续部署在同一个 API server 内，复用现有分派和 External REST router： + +```text +Agent 调用语义工具 + → MCP 层选择对应 operation，并转换参数位置 + → 进程内调用现有 External REST router + → 复用鉴权、scope、owner、校验、幂等、计费和业务处理 + → MCP 返回业务结果或结构化错误 +``` + +多功能工具的一次调用只选择一个操作。工具聚合不意味着批量执行、自动连续写入或新增跨操作事务。文件上传仍由调用方完成二进制传输。 + +## 3. 说明与参数的共同设计 + +### 3.1 工具说明 + +每份说明包含： + +1. 用途：用户希望完成什么任务时选择本工具。 +2. 操作选择：多功能工具列出各 action 的用途，解释容易混淆的选择。 +3. 结果：立即返回业务结果，还是返回异步任务 ID；有哪些重要的降级或结果边界。 + +字段格式、枚举、必填关系放入参数 schema 和字段说明，避免把全部接口校验细节堆进工具 description。付费、删除等重要影响应明确表达，但 description 和风险注解不替代后端权限校验；宿主负责结合用户已给出的授权作调用决策。 + +### 3.2 多功能与单功能工具 + +多功能工具采用 `action + input`，input 必须提供对应 action 的明确字段、类型、必填条件和枚举，不能只是任意 JSON 对象。服务端在分派前校验所选操作，避免不相干分支的参数混入底层请求。 + +示意调用（示例 ID 仅为说明）： + +```json +{ + "action": "edit", + "input": { + "sourceReferenceId": "", + "prompt": "把衣服改成红色", + "projectId": "" + }, + "idempotencyKey": "" +} +``` + +单功能工具直接声明业务字段，不强行添加 action 或 input 包装。`kind`、`sliceMode`、视频 `mode` 等原有业务选择保留原名，它们与工具级 action 职责不同。 + +工具参数中的 ID 由 MCP 层放入 REST 路径或查询，业务输入放入请求体，`idempotencyKey` 转为 `Idempotency-Key` header。具体参数保留现有命名、类型和条件；下表列的是关键字段，并非完整 schema 或排他白名单。未逐项列出的可选字段按对应 OpenAPI operation 核对，不把站内 DTO 的内部字段顺带开放。 + +### 3.3 共用行为 + +- 九类生成 POST 继续要求稳定幂等键，并返回 `202 + operationId`；工具不能把受理当成生成完成。 +- 项目创建、项目资源登记、文件夹创建的 REST API 支持可选幂等键，新工具设计应保留该能力。当前 MCP bridge 主要按 required header 推导幂等参数，实现时须明确接入这些可选 header；素材记录创建 API 不在该可选幂等合同中。 +- 相同 API 能力出现在不同语义入口时，参数约束、底层请求和结果语义保持一致。重试或切换入口恢复同一逻辑请求时，保留原 API 操作、规范请求和幂等键，不因换工具名创建新任务。 +- `projectId`、`assetFolderId`、`assetLabel`、`canvasCompletion` 等目标参数只在对应 API 支持时提供。UI 素材提取使用 `spritesheetLabel`；各生成族不共享未经核对的字段全集。 +- owner 由 API Key 确定，不让 Agent 指定身份，不把 API Key 放进工具参数。 +- 业务结果继续使用结构化返回；业务失败沿用安全错误语义，不把失败包装成成功。生成成功、素材登记、画布落位、切片成功分别按实际结果判断。 +- 读取、写入、付费与删除应在说明和注解中准确表达。注解作用于整个工具，因此将删除独立成工具；`openWorldHint` 不等同于付费标记。 + +## 4. 工具说明与操作映射 + +以下共 15 个候选工具。删除从项目管理、素材库整理中移出，统一放入 XV。action 名称是本设计的候选值，不表示已经上线。 + +### I. 查找画布项目 + +**说明：** 查找已有画布项目，或读取指定项目的完整内容。先通过列表或最近项目确定目标，再读取详情获取画布、图层和资源。 + +| action | 关键参数 | 现有 operationId | +| --- | --- | --- | +| `list` | 无 | `listEditorProjects`，固定 `view=summary` | +| `recent` | 无 | `loadRecentEditorProject` | +| `get` | 必填 `projectId` | `getEditorProject` | + +列表使用既有摘要视图，不能退回全量项目快照。当前接口没有分页、limit 或名称搜索参数，工具不虚构这些字段。名称匹配基于读取结果；有歧义时向用户明确候选，不静默创建替代项目。 + +### II. 管理画布项目 + +**说明：** 创建新的画布项目，或修改已有项目的名称。 + +| action | 关键参数 | 现有 operationId | +| --- | --- | --- | +| `create` | 可选 `title`；可选幂等键 | `createEditorProject` | +| `rename` | 必填 `projectId`、`title` | `renameEditorProject` | + +一次创建仅创建项目，不默认追加创建同名素材文件夹。删除使用 XV。 + +### III. 查找与读取素材 + +**说明：** 查看账号素材库或指定项目中的资源，并为已有素材获取临时下载地址。 + +| action | 关键参数 | 现有 operationId | +| --- | --- | --- | +| `list_library` | 无 | `getEditorAssetLibrary` | +| `get_project_resources` | 必填 `projectId` | `getEditorProject` | +| `get_download_url` | `objectKey`；可选 `expireSeconds` | `getExternalAssetReadUrl` | + +项目资源查询复用项目详情，不新增资源查询 API。建议仅投影其资源部分，具体输出结构在实现前固定，并保留资源身份字段。 + +读取素材记录、获取文件地址与查看媒体内容是不同操作。工具不提供本地下载、关键词检索或相似素材搜索。临时签名 URL 用于访问媒体，不作为持久化生成引用。REST 还支持 `legacyPublicPath`；语义入口优先使用稳定 objectKey，是否保留该兼容查询字段在完整 schema 评审时明确，不改 REST 契约。 + +### IV. 办理素材上传 + +**说明：** 获取文件直传凭证，并在调用方完成上传后确认素材对象。文件传输由调用方执行。 + +| action | 必填参数 | 常用可选参数 | 现有 operationId | +| --- | --- | --- | --- | +| `create_upload_ticket` | `legacyPrefix`、`fileName` | `contentType`、`pathSegments`、`maxSizeBytes` 等 | `createExternalDirectUploadTicket` | +| `confirm_upload` | `objectKey`、`assetKind` | `bucket`、`contentType`、`contentLength`、`contentHash` 等 | `confirmExternalAssetObject` | + +流程为“申请凭证 → 调用方按返回的 OSS 表单直传参数上传 → 确认对象”。不把上传协议笼统写成固定 PUT。工具不接受本地路径或 base64，不代上传。对象确认后若需要项目资源或素材库记录，再调用相应登记操作；确认对象不等于完成这些登记。 + +`ownerUserId` 由后端账号身份决定，不作为 Agent 可选参数。 + +### V. 生成图片 + +**说明：** 根据文字和可选参考图生成图片，支持普通图片、视觉规范、角色、UI 设计、宣发素材和快速参考变体。提交后通过任务 ID 查询结果。 + +映射 `generateExternalEditorImage`，无需 action。 + +| 参数 | 约束与用途 | +| --- | --- | +| `prompt` | 必填，生成内容描述 | +| `kind` | 可选；省略表示普通图，其他用途为 `spec`、`character`、`quick-edit`、`ui-design`、`publication-material` | +| `referenceImageSrcs` | 可选参考图；具体引用和组合约束沿用 API | +| `model`、`aspectRatio`、`imageSize`、`size` | 可选输出配置，枚举及组合以当前 schema 为准 | +| `style` | 可选风格；适用范围沿用对应 kind 的现有处理 | +| `screenColor` | 可选纯色抠像背景色，见下文 | +| 目标与落位字段 | 按当前接口支持提供项目、素材库和画布目标 | + +**背景色已经通过 API 开放。** screenColor 可传画布支持的颜色 hex，例如 `#CFEFFF`；传 `"auto"`、null 或省略，由服务端自动选择。它描述生成及后续抠图流程的纯色背景，不保证最终产物保留该底色；不能据此承诺“最终图片指定底色”或通用背景替换能力。 + +不额外引入与 kind 重复的 action；不添加未开放的 `scene` 生成入口。 + +### VI. 修改图片 + +**说明：** 对已有图片做定向修改、生成参考变体或移除背景。定向修改使用已登记资源；快速变体通过参考图生成新版本。提交后通过任务 ID 查询结果。 + +| action | 关键参数 | 现有 operationId | +| --- | --- | --- | +| `edit` | 必填 `sourceReferenceId`、`prompt`；其余为编辑 API 的可选字段 | `editExternalEditorImage` | +| `variation` | 必填 `prompt`；参考输入使用 `referenceImageSrcs`；其他字段复用图片生成 | `generateExternalEditorImage`，适配层固定 `kind=quick-edit` | +| `remove_background` | 必填 `sourceImageSrc`；可选 `backgroundMode`、条件允许的 `screenColor` 及目标字段 | `removeExternalEditorImageBackground` | + +来源参数保留真实差异： + +- edit 的 sourceReferenceId 只接受当前账号已登记的项目资源 ID 或素材 ID，不能用 objectKey 或 URL 代替。 +- 去背景的 sourceImageSrc 支持当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID，只处理允许的静态图片。 +- 变体的参考来源沿用生成 API；不新造含糊的统一 source 字段。其参考输入必填性、有效引用等条件沿用 quick-edit 的现有契约，不从图片生成 schema 只有 prompt 必填就推断所有用途无需前置条件。 + +去背景 backgroundMode 省略或 null 时默认为 `complex`。complex 做语义分割；`flat` 用于纯色背景。screenColor 仅在 flat 下可传非 null 值，支持 `auto`、`#RRGGBB`，省略或 null 自动检测；complex 下传非 null screenColor 会被拒绝。不能直接照搬图片生成的全部背景色组合规则。 + +需要原位替换时，编辑和去背景沿用各自 API 的 `projectId + targetLayerId` 来源绑定要求；不能用目标图层 ID 绕过账号归属与对象一致性校验。变体入口不额外承诺原位替换。 + +variation 与 V 的 kind=quick-edit 是合理交集，复用同一输入定义、底层请求和结果语义，不让调用方重复提供固定 kind。 + +### VII. 生成图标图集 + +**说明：** 根据已登记的参考规范和图标清单生成图集，并按指定方式尝试拆分独立图标。 + +映射 `generateExternalEditorIconSpritesheet`，无需 action。 + +- 必填：`referenceId`、`iconDescriptions`、`sliceMode`。 +- referenceId 为当前账号已登记为 `icon-spec` 的项目资源或素材 ID，不接受 objectKey 或 URL 代替。 +- `sliceMode=grid`：提供需求对应的 `gridX`、`gridY`，各为 1–32，不传 sliceCount。 +- `sliceMode=connected-components`：可用 `sliceCount`（1–256）约束张数，不提供 gridX/gridY。 +- 可选：`referenceImageSrcs`、`screenColor`、`style`、模型、比例、尺寸及目标字段。 + +sliceMode 没有默认值。主规范引用使用 referenceId，不用辅助 referenceImageSrcs 替代。此工具包含生成步骤，不是任意已有图片的通用裁切工具。切片未完成时可能仍有完整图集，结果必须保留 sliceWarning。 + +### VIII. 提取 UI 素材 + +**说明：** 以已有 UI 设计图为参考，生成组件素材图集并尝试拆分，供后续界面制作使用。 + +映射 `extractExternalEditorUiDesignAssets`，无需 action。 + +- 必填：`sourceImageSrc`、`aspectRatio`、`imageSize`。 +- 可选：`model`、`referenceImageSrcs`、`screenColor`、`spritesheetLabel` 和对应目标字段。 +- 结果命名沿用 spritesheetLabel，不强行改成其他生成接口的 assetLabel。 + +接口包含生成过程，不保证把原图中的组件逐像素原样裁出。与 VII 的区别是：VII 以规范和明确图标清单生成，VIII 以已有 UI 设计图提取组件语义。两者都须分别判断图集与切片结果。 + +### IX. 生成角色动画 + +**说明：** 根据角色源图和动作描述，生成角色动画预览与帧序列。 + +映射 `generateExternalEditorCharacterAnimation`，无需 action。 + +- 来源必填：`sourceLayerId`、`sourceImageSrc`、`sourceWidth`、`sourceHeight`。 +- 动作必填：`promptText`。 +- 输出必填：`resolution`、`ratio`、`frameCount`、`durationSeconds`、`model`。 +- 可选：`screenColor`、`sourceResourceId`、目标与落位字段等。 + +来源与尺寸先从真实资源中取得，不为简化调用伪造图层 ID 或源图尺寸。此工具不提供已有动画文件编辑。正式动画结果按现有帧序列合同消费，不重复用第一帧手工登记一份动画。 + +### X. 生成视频 + +**说明：** 根据文字和模型支持的参考图片、视频或音频生成视频片段。 + +映射 `generateExternalEditorVideo`，无需 action。 + +- 必填：`prompt`、`model`、`aspectRatio`、`durationSeconds`、`resolution`、`mode`、`sound`。 +- 可选参考：`referenceImageSrcs`、`referenceVideoSrcs`、`referenceAudioSrcs`。 +- 其他可选项：当前 API 支持的 `webSearchEnabled`、目标与落位字段等。 + +保留 mode 作为视频业务模式，与工具级 action 无关。参考媒体、时长、分辨率、声音和其他选项的组合以所选模型的当前契约为准，不暗示每个模型支持所有组合。 + +### XI. 生成音频 + +**说明：** 生成音效或背景音乐。短声音、环境声和交互反馈选择音效；配乐选择背景音乐。 + +| action | 必填参数 | 常用可选参数 | 现有 operationId | +| --- | --- | --- | --- | +| `sound_effect` | `prompt` | `duration`、`loop`、`model`、目标字段 | `generateExternalEditorSoundEffect` | +| `background_music` | `gptDescriptionPrompt`、`makeInstrumental` | 目标与落位字段 | `generateExternalEditorBackgroundMusic` | + +当前音效 duration 是可选字段，省略或 null 表示自动，手动时长范围为 0.5–30 秒。不沿用“必须填写时长”的过期说法。两个分支保留各自提示词字段，不另外实现一套提示词翻译协议。两者均异步受理。 + +### XII. 编辑画布 + +**说明：** 读取画布、保存完整布局，或登记供图层引用的项目资源。保存布局需要基于最新画布版本。 + +| action | 关键参数 | 现有 operationId | +| --- | --- | --- | +| `get` | 必填 `projectId` | `getEditorProject` | +| `save_layout` | 必填 `projectId`、`viewport`、`layers`、`expectedRevision` | `saveEditorProjectCanvas` | +| `register_resource` | 必填 `projectId`、`imageSrc`、`width`、`height`、`sourceType`；支持可选幂等键 | `createEditorProjectResource` | + +save_layout 保存完整默认画布布局，不提供只传一个图层的局部 patch 语义；expectedRevision 来自最新读取，版本冲突按现有 API 处理。 + +register_resource 只登记资源，并不自动创建画布图层。正常生成结果落画布优先使用生成接口的 canvasCompletion。可选 objectKey、assetObjectId、assetKind、帧序列等字段按资源登记 schema 提供，不从临时 UI 状态推导正式来源。 + +### XIII. 整理素材库 + +**说明：** 管理素材文件夹和素材记录，包括新建、改名、移动以及登记已有媒体。 + +| action | 关键参数 | 现有 operationId | +| --- | --- | --- | +| `create_folder` | 必填 `label`；可选 `sortOrder`、幂等键 | `createEditorAssetFolder` | +| `update_folder` | 必填 `folderId`；可选 `label`、`collapsed` | `updateEditorAssetFolder` | +| `create_asset` | 必填 `folderId`、`label`、`imageSrc`、`width`、`height`、`sourceType` | `createEditorAsset` | +| `update_asset` | 必填 `assetId`；可选 `label`、`folderId` | `updateEditorAsset` | + +移动素材复用 update_asset 的 folderId，不额外拆一个重复操作。可选更新字段的有效性按现有 API 处理。create_asset 只登记元数据，不上传文件、不触发生成；生成接口已经完成入库时不重复登记。删除使用 XV。 + +### XIV. 查看生成进度与结果 + +**说明：** 查询一次已提交生成任务的当前状态。完成时返回结果，失败时返回错误；尚未完成时按建议间隔再次查询。 + +映射 `getExternalEditorGenerationJob`，无需 action；必填 `operationId`。 + +- 每次调用只查询一次，不在 MCP 服务端长时间阻塞到任务完成。 +- `queued/running`：读取进度和 pollAfterMs，继续等待。 +- `completed`：消费 result，并保留 warning 与 sliceWarning 等真实降级信息。 +- `failed`：返回已有脱敏错误。 +- 跨账号任务与不存在任务沿用同一不可见语义。 + +收到 operationId 后优先直接查询。若提交响应丢失、尚未取得 operationId，不能靠查询工具凭空恢复：按现有幂等合同，复用原 API 操作、原请求和原幂等键重试以取得受理结果；不能换键重提。查询超时不改变服务端任务状态。 + +### XV. 删除资源 + +**说明：** 删除指定项目、素材文件夹或素材记录。按精确 ID 操作，调用前明确目标及删除范围，并取得对应用户授权。 + +| action | 必填参数 | 现有 operationId | +| --- | --- | --- | +| `delete_project` | `projectId` | `deleteEditorProject` | +| `delete_folder` | `folderId` | `deleteEditorAssetFolder` | +| `delete_asset` | `assetId` | `deleteEditorAsset` | + +工具统一标记删除风险。项目删除沿用默认画布与项目资源元数据级联清理语义。文件夹删除将其素材记录移到默认文件夹，默认文件夹不能删除；素材删除删除记录并处理关联精选审核状态。文件夹和素材记录删除不等于删除底层 OSS 媒体。 + +不增加批量、按名称或模糊匹配删除，不用一个可伪造的 confirm 参数替代真实用户授权和后端鉴权。 + +## 5. 实现前仍需明确的事项 + +1. 最终英文工具名与完整 action schema；条件参数如何在目标 MCP 客户端中准确展示和校验。 +2. III 的项目资源投影结构及 legacyPublicPath 保留策略；各工具结果保持原样或裁剪时的精确字段。 +3. 新旧工具替换、并存或迁移的具体选择。本文不预设双套目录、默认开关或 api_* 逃生入口。 +4. 更新服务级 instructions、工具说明与相关使用资料，确保与实际广告的工具一致；文档存储和发布机制另行讨论。 + +实现验收围绕实际风险：操作路由和参数位置正确、缺失或错分支参数不触发副作用、原有 owner/scope 校验有效、同一逻辑生成幂等恢复、图集降级告警保留、画布 revision 冲突保留，以及重复语义入口调用同一底层能力的结果一致性。本文完成不代表这些运行时验证已经通过。 + +## 6. 核对入口 + +- [External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)：operation、参数、请求体、响应与公开字段权威。 +- [External API 路由](../../server-rs/crates/api-server/src/modules/external_api.rs)：实际路由挂载。 +- [MCP 实现](../../server-rs/crates/api-server/src/external_mcp.rs)：工具生成、schema、资源和进程内分派。 +- [External 编辑器接口](../../server-rs/crates/api-server/src/external_editor_api.rs)：鉴权、请求处理与生成受理。 +- [AGC 抠图模式与背景色透传](./【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)：去背景模式与背景色已有合同。 + +当前参数事实按 2026-09-23 的仓库内容核对；后续实现时再次以代码与 OpenAPI 为准，发现变动同步修订本文，不维护第二份脱离 API 的字段真相。 diff --git a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md index fef7460d7..c87066850 100644 --- a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md +++ b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md @@ -78,6 +78,8 @@ provider 原图已保存但透明背景处理最终失败时，worker 保留原 ## 托管远程 MCP +后续语义工具的设计参考见 [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)。该文档仅规划复用现有 External API 的新工具说明、操作划分和参数；尚未实现，不替代下述现役 MCP 契约。 + `/api/external/v1/mcp` 是 Genarrative 托管的远程端点，Agent 只需配置 URL 和现有 API Key，不安装本地 MCP server。首版兼容 MCP `2025-11-25` initialize 生命周期，使用 JSON-RPC 2.0 和 Streamable HTTP，支持 `initialize`、`notifications/initialized`、`ping`、`tools/list`、`tools/call`、`resources/list`、`resources/read`。服务端使用无协议 session 的 JSON direct 模式，不依赖 sticky session，也不把 `Mcp-Session-Id` 作为业务身份。 MCP transport 的 DNS rebinding 防护必须同时允许正式入口 `www.genarrative.world` / `genarrative.world`、开发入口 `dev.genarrative.world` 和本机开发入口；对应 HTTPS Origin 也必须与公开环境同步登记。新增公开环境域名时，必须在发布前使用该域名的真实 `Host` 和 `Origin` 执行 `initialize` 回归，不能只用 `localhost` 单测证明端点可用。