升级mcp，增加按语义分类的工具。旧工具不变 #493

Merged

lhk229 merged 12 commits from feat/mcp-upgrade into master 2026-09-24 17:19:45 +08:00

Conversation 1 Commits 12 Files Changed 13

+2147 -208

lhk229 commented 2026-09-23 13:52:47 +08:00

Member

Copy Link

Copy Source

No description provided.

lhk229 added 3 commits 2026-09-23 13:52:47 +08:00

整理外部MCP语义工具说明与参数设计 ... 2ab849652e

新增十五个候选工具的说明、操作映射和参数边界
明确仅复用现有External API及语义工具尚未实现的状态
补充背景色、上传、异步恢复与删除行为说明
同步文档总览、外部接口父规范和共享文档地图

新增外部MCP语义工具并保留原有入口 ... ecb0dc08b8

新增十五个语义工具及中文说明和分支参数契约
复用现有API分派并支持新入口的可选创建幂等键
保留全部原工具和API并补充分派与兼容回归测试
同步工程文档及验收记录并注明本地数据库阻断的运行验证

合并master更新到MCP改造分支 ... 8835311af3

合入最新master的AGC提示词整理与发布反馈修复
保留现有MCP语义工具实现与全部原有入口
验证MCP定向测试和发布反馈测试及文档编码检查

lhk229 added 1 commit 2026-09-23 14:28:19 +08:00

Merge branch 'master' into feat/mcp-upgrade e0d37edff2

lhk229 added 1 commit 2026-09-23 15:18:03 +08:00

完成MCP语义工具运行验收并收口文档 ... 23b2a33257

补充本地服务启动、MCP认证及新旧工具实际调用的验收证据
记录幂等、非法字段拒绝、测试数据清理及未验证范围
将已完成里程碑和实施计划归入正式技术方案并删除临时计划

lhk229 added 1 commit 2026-09-23 15:18:36 +08:00

Merge remote-tracking branch 'origin/master' into feat/mcp-upgrade 63a8e25f25

lhk229 self-assigned this 2026-09-23 19:06:11 +08:00

lhk229 added 1 commit 2026-09-24 11:39:49 +08:00

Merge remote-tracking branch 'origin/master' into feat/mcp-upgrade 7ca7e9e0e2

lhk229 added 1 commit 2026-09-24 14:12:48 +08:00

合并最新master 991183fb2f

lhk229 added 3 commits 2026-09-24 16:12:11 +08:00

更新MCP整体使用说明 ... 2499b4f76e

精简 instructions 为服务能力和跨工具共同约定
取消强制创建同名素材文件夹与双重落库要求
同步技术方案和共享文档索引

更新MCP资源文档与工具调用指南 ... 4589908e55

精简共用 Skill 主入口并更新工具选择和 API 映射
补充 MCP 参数示例、上传、异步轮询和画布保存流程
校准鉴权、幂等、按需落库及结果告警说明
同步技术方案与共享文档索引

收口MCP改造范围与验收记录 ... 53cf0304ae

更新 instructions 和 resources 的最终完成状态
补齐全工具实测、真实付费生成及最新回归结果
明确独立问题跟踪和部署后待验证范围

lhk229 marked the pull request as ready for review 2026-09-24 16:12:47 +08:00

lhk229 commented 2026-09-24 16:22:58 +08:00

Author

Member

Copy Link

Copy Source

代码审查（feat/mcp-upgrade → master）

总体结论：认可，建议合并。 新增 15 个语义工具与 29 个旧工具并存，语义层只做 action 选择与参数位置转换，业务校验与副作用仍由 External router 承担，分层干净。本地 cargo test -p api-server external_mcp 24/24 通过。

主要优点

1. 单一数据源：semantic.rs 的 schema 全部从内嵌 OpenAPI + MCP_OPERATIONS 派生，不复制字段定义，且保留了 body 的 if/then/allOf 条件约束（semantic.rs:184）。
2. 兼容性有保障：semantic_catalog_appends_tools_without_changing_legacy_definitions 逐字节断言旧工具定义不变；旧分派路径传 optional_idempotency_key=None，legacy-ignored 测试锁定旧行为。
3. 幂等处理清晰：9 个生成操作在 schema 层强制 idempotencyKey；仅 3 个创建类 action 接受可选幂等键并转为 HTTP 头（semantic.rs:333-338），有专门测试锁定。
4. 安全边界正确：confirm_upload 移除 ownerUserId（owner 由 API Key 决定）；结构校验在构建 HTTP 上下文前失败，scope 检查复用 REST 层且不泄露 owner 信息（均有测试覆盖）。
5. 测试覆盖扎实：31 个 action 的映射全覆盖单测 + RPC 级集成测试。

非阻塞建议

• validate_fields 只校验顶层结构，嵌套/跨字段约束（如 remove_background 的 screenColor×flat 条件）仍依赖 REST 返回 400，错误时机晚于结构错误。代码注释已说明这一取舍，可接受。
• destructive 注解用字段名启发式判断（canvasCompletion/targetLayerId，semantic.rs:138-145），后续新增含类似字段的写操作时需注意是否会被正确标记。
• MCP_INSTRUCTIONS 重写后删除了 sliceMode 等具体指引，已确认改由 semantic_tools.json 中各工具 description 承载（如 generate_icon_spritesheet 说明完整），无信息丢失。
• 文档同步到位：docs/README、document-map 与新增技术方案文档（2026-09-23）齐全，符合仓库规范。

## 代码审查（feat/mcp-upgrade → master） **总体结论：认可，建议合并。** 新增 15 个语义工具与 29 个旧工具并存，语义层只做 action 选择与参数位置转换，业务校验与副作用仍由 External router 承担，分层干净。本地 `cargo test -p api-server external_mcp` 24/24 通过。 **主要优点** 1. **单一数据源**：`semantic.rs` 的 schema 全部从内嵌 OpenAPI + `MCP_OPERATIONS` 派生，不复制字段定义，且保留了 body 的 `if/then/allOf` 条件约束（`semantic.rs:184`）。 2. **兼容性有保障**：`semantic_catalog_appends_tools_without_changing_legacy_definitions` 逐字节断言旧工具定义不变；旧分派路径传 `optional_idempotency_key=None`，`legacy-ignored` 测试锁定旧行为。 3. **幂等处理清晰**：9 个生成操作在 schema 层强制 `idempotencyKey`；仅 3 个创建类 action 接受可选幂等键并转为 HTTP 头（`semantic.rs:333-338`），有专门测试锁定。 4. **安全边界正确**：`confirm_upload` 移除 `ownerUserId`（owner 由 API Key 决定）；结构校验在构建 HTTP 上下文前失败，scope 检查复用 REST 层且不泄露 owner 信息（均有测试覆盖）。 5. **测试覆盖扎实**：31 个 action 的映射全覆盖单测 + RPC 级集成测试。 **非阻塞建议** - `validate_fields` 只校验顶层结构，嵌套/跨字段约束（如 remove_background 的 `screenColor`×`flat` 条件）仍依赖 REST 返回 400，错误时机晚于结构错误。代码注释已说明这一取舍，可接受。 - `destructive` 注解用字段名启发式判断（`canvasCompletion`/`targetLayerId`，`semantic.rs:138-145`），后续新增含类似字段的写操作时需注意是否会被正确标记。 - `MCP_INSTRUCTIONS` 重写后删除了 sliceMode 等具体指引，已确认改由 `semantic_tools.json` 中各工具 description 承载（如 `generate_icon_spritesheet` 说明完整），无信息丢失。 - 文档同步到位：docs/README、document-map 与新增技术方案文档（2026-09-23）齐全，符合仓库规范。

lhk229 added 1 commit 2026-09-24 16:43:57 +08:00

修正MCP语义工具的破坏性风险注解 ... e4adde0573

按 API 操作显式声明风险并汇总到工具级注解
修正上传确认可覆盖已有对象元数据的漏标
增加工具风险注解回归测试并同步工程文档

lhk229 requested review from Developers 2026-09-24 16:49:47 +08:00

lhk229 merged commit a07bff85ec into master 2026-09-24 17:19:45 +08:00

lhk229 deleted branch feat/mcp-upgrade 2026-09-24 17:19:45 +08:00

Sign in to join this conversation.

Reviewers

No Reviewers

GenarrativeAI/Developers

Labels

Clear labels

Compat/Breaking

Breaking change that won't be backward compatible

Kind/Bug

Something is not working

Kind/Documentation

Documentation changes

Kind/Enhancement

Improve existing functionality

Kind/Feature

New functionality

Kind/Security

This is security issue

Kind/Testing

Issue or pull request related to testing

Priority

Critical

1

The priority is critical

Priority

High

2

The priority is high

Priority

Low

4

The priority is low

Priority

Medium

3

The priority is medium

Reviewed

Confirmed

1

Issue has been confirmed

Reviewed

Duplicate

2

This issue or pull request already exists

Reviewed

Invalid

3

Invalid issue

Reviewed

Won't Fix

3

This issue won't be fixed

Status

Abandoned

3

Somebody has started to work on this but abandoned work

Status

Blocked

1

Something is blocking this issue or pull request

Status

Need More Info

2

Feedback is required to reproduce issue or to continue work

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

HuangJiaJia JenkenB k88936 (王德宇) kdletters (段舒康) laura2008 (王乐) lhk229 (孔令弘) Loer (农洛儿) loong suzmii (董羽秦) taobaisu (叶东旭) wuxiangwanzi (王子民) YixuanLiu ziyu

No Assignees lhk229

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GenarrativeAI/Genarrative#493