From 23b2a33257d7a458c60b68180eeda24358191c92 Mon Sep 17 00:00:00 2001 From: Linghong Date: Wed, 23 Sep 2026 07:16:14 +0000 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E6=88=90MCP=E8=AF=AD=E4=B9=89?= =?UTF-8?q?=E5=B7=A5=E5=85=B7=E8=BF=90=E8=A1=8C=E9=AA=8C=E6=94=B6=E5=B9=B6?= =?UTF-8?q?=E6=94=B6=E5=8F=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充本地服务启动、MCP认证及新旧工具实际调用的验收证据 记录幂等、非法字段拒绝、测试数据清理及未验证范围 将已完成里程碑和实施计划归入正式技术方案并删除临时计划 --- ...实施计划】外部MCP语义工具并存-2026-09-23.md | 35 ------------- ...里程碑】外部MCP语义工具并存-2026-09-23.md | 51 ------------------- ...】外部MCP语义工具说明与参数设计-2026-09-23.md | 17 +++++++ 3 files changed, 17 insertions(+), 86 deletions(-) delete mode 100644 docs/project-memory/plans/【实施计划】外部MCP语义工具并存-2026-09-23.md delete mode 100644 docs/project-memory/plans/【里程碑】外部MCP语义工具并存-2026-09-23.md diff --git a/docs/project-memory/plans/【实施计划】外部MCP语义工具并存-2026-09-23.md b/docs/project-memory/plans/【实施计划】外部MCP语义工具并存-2026-09-23.md deleted file mode 100644 index b0665ac29..000000000 --- a/docs/project-memory/plans/【实施计划】外部MCP语义工具并存-2026-09-23.md +++ /dev/null @@ -1,35 +0,0 @@ -# 外部 MCP 语义工具并存实施计划 - -| 字段 | 值 | -| --- | --- | -| Milestone | [外部 MCP 语义工具并存](./【里程碑】外部MCP语义工具并存-2026-09-23.md) | -| Status | awaiting-runtime-verification | -| Owner | Agent | - -## 修改边界 - -MCP 模块、所属工具提示词、定向测试、主规范及文档索引。REST DTO/路由/OpenAPI、resources/instructions、数据库和 CLI 保持原样。 - -## 实现顺序 - -1. 评审主规范和里程碑，收口剩余技术歧义。 -2. 在 MCP 内增加语义注册与 schema 构造；提示词置于所属 prompts 目录。 -3. 新工具转换为现有 operation 参数后复用分派；可选幂等只影响新入口。 -4. 验证各 action 映射、旧目录兼容、错误与权限边界；同步文档状态。 - -## 验证命令 - -- `cargo test --locked -p api-server external_mcp` -- `cargo test --locked -p api-server external_api_auth` -- `cargo test --locked -p api-server external_`（覆盖认证及相关 External API 回归） -- 对修改的 Rust 文件运行 `rustfmt --check`。 -- `npm run dev:api-server` 与实际端口 `/healthz`；只启动/停止本任务进程。 -- `npm run check:doc-index`、`npm run check:encoding`、`git diff --check`。 - -## 风险与回滚点 - -schema 条件保真、幂等键可选分支和新增目录体积是重点。只增加 MCP 适配，不复制业务处理；异常时可回滚新增语义注册而不迁移数据。不得将内存 router 测试作为真实 Provider/账号验收。 - -## 当前状态 - -实现与自动化回归完成；155 项 External 相关测试通过。运行时启动因本地 SpacetimeDB 连接拒绝而未完成健康检查，详情见里程碑证据表。恢复可用的本地数据库配置后只需补跑 smoke 和验收，不重复扩展业务实现。 diff --git a/docs/project-memory/plans/【里程碑】外部MCP语义工具并存-2026-09-23.md b/docs/project-memory/plans/【里程碑】外部MCP语义工具并存-2026-09-23.md deleted file mode 100644 index fbd31452d..000000000 --- a/docs/project-memory/plans/【里程碑】外部MCP语义工具并存-2026-09-23.md +++ /dev/null @@ -1,51 +0,0 @@ -# 外部 MCP 语义工具并存 - -| 字段 | 值 | -| --- | --- | -| Version | 1.0 | -| Status | awaiting-runtime-verification | -| Date | 2026-09-23 | -| Parent Spec | [外部 MCP 语义工具说明与参数设计](../../technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md) | - -## 目标与范围 - -同一托管 MCP 增加主规范的 15 个语义工具及完整输入说明；复用现有 External API，实现 action 分派、参数位置转换及同源业务结果。 - -## 非目标 - -不删除、隐藏、重命名或改变任何旧工具/API；不新增 REST 能力，不修改 SpacetimeDB，不改 resources、instructions、CLI、独立 Skill 或发布页，不部署。 - -## 依赖与前置条件 - -主规范第 5 节固定工具名、schema、结果、可选幂等与新旧并存方式；开发前完成独立评审。 - -独立评审结论：范围、兼容、失败语义与验收无阻塞项；分支 schema 与运行时均须拒绝错分支字段，可选幂等不得改变旧入口行为。 - -## 验收标准 - -- [x] 15 个新工具和原目录同时可见，原工具定义保持一致。 -- [x] 每个 action 只调用一个已有 operation；路径、查询、body 与幂等头正确。 -- [x] 错 action、缺字段、跨分支字段和 ownerUserId 注入在分派前拒绝。 -- [x] 必填及可选幂等键转发正确，重复语义入口不改变规范请求。 -- [x] 成功结果、告警和结构化业务错误沿用既有处理，无额外投影。 -- [x] API Key/owner/scope 边界继续在现有 router 生效。 -- [x] 定向 Rust 测试、格式、编码和文档检查通过。 -- [ ] 本地 healthz smoke 通过。 - -## 证据要求 - -自动化覆盖目录、分派、参数、幂等、传输和认证；运行时执行本地 API smoke。真实账号/Provider/客户端未验证项单独记录，不自动触发付费生成。 - -## 验收证据 - -| 条款 | 验证 | 结果与边界 | -| --- | --- | --- | -| 工具目录与字段合同 | `cargo test --locked -p api-server external_mcp` | 24 项通过；44 个工具可见，31 个 action 路由覆盖，原工具序列化定义保留，全部 schema 无外部引用且满足既有体积上限 | -| 错分支、请求映射、幂等 | 同上 | 错分支/owner 注入拒绝，路径编码和查询/body 分离，可选/必填 key，两个 quick-edit 入口的规范请求一致 | -| 权限、异步与旧 REST | `cargo test --locked -p api-server external_` | 155 项通过；含上述 24 项、MCP 内外两次认证和 scope 403、既有跨 owner 不可见、幂等、参数校验、OpenAPI 与 Skill 回归 | -| 编译与文本 | `cargo check --locked -p api-server`、定向 rustfmt、文档索引、编码和 diff 检查 | 通过 | -| 运行时 | `npm run dev:api-server` 与本地 healthz | 可执行文件编译成功、BgFilter worker 启动；API 启动被本地 SpacetimeDB 连接拒绝阻断，healthz 与未认证 MCP initialize 超时。本次使用隔离测试数据库名，未发布数据库或调用付费生成，启动进程已清理 | - -未验证：真实账号下的端到端数据库读写、付费 Provider 生成、外部 MCP 客户端对 oneOf 参数的展示与使用、远端部署。内存 router 和同源请求映射证明适配链路，不替代这些真实运行环境验收。 - -剩余工作仅为在可用的本地数据库配置下重跑启动 smoke，并取得本里程碑验收结论；不自动扩大为开发环境修复或 resources/instructions 改造。 diff --git a/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md b/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md index 19452b90f..e3e5c1ac3 100644 --- a/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md +++ b/docs/technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md @@ -326,6 +326,23 @@ register_resource 只登记资源，并不自动创建画布图层。正常生 验证工具目录追加与旧定义一致、全部 action 路由与字段位置、必填和错分支拒绝、可选/必填幂等头、quick-edit 与普通生成入口等价、原 owner/scope 边界、结构化结果/告警和 revision 冲突透传。运行 api-server 定向测试与本地 healthz smoke；真实账号、付费 Provider 和具体 MCP 客户端尚未验证时明确记录，不能将单元测试当作线上验收。 +### 5.4 实现与验收结果（2026-09-23） + +本轮实现与本地验收完成。新增 15 个语义工具与原有 29 个工具同时可见；resources/instructions 保持原样。已完成的里程碑和实施计划收口到本节。 + +| 验证范围 | 证据与结果 | +| --- | --- | +| 工具与参数合同 | `cargo test --locked -p api-server external_mcp`：24 项通过，覆盖 44 个工具、31 个 action、旧定义保留、schema 展开、参数映射、错分支拒绝、必填/可选幂等和等价入口 | +| 认证与既有 API 回归 | `cargo test --locked -p api-server external_`：155 项通过，含 MCP 内外认证、scope 拒绝、跨 owner 隔离、异步及 OpenAPI 回归 | +| 编译与文本检查 | `cargo check --locked -p api-server`、定向 rustfmt、文档索引、编码和 diff 检查通过 | +| 本地服务启动 | 先通过 `npm run dev:spacetime` 启动 SpacetimeDB 2.8.3 并发布隔离数据库，再通过 `npm run dev:api-server` 启动同一目标的 API 和 worker；`/v1/ping`、`/healthz`、`/readyz` 均返回 200 | +| MCP 真实 HTTP 链路 | 未认证返回 401；使用隔离数据库中的临时测试 API Key，initialize 成功，tools/list 返回 44 个工具且包含全部 29 个旧工具，resources/list 返回原有 7 个资源 | +| 本地数据库读写 | 新工具创建/列表/重命名/读取/删除成功；同键重复创建返回同一项目；旧工具读写与新工具互通；重复语义读取保留完整项目；ownerUserId 额外字段被拒绝且未产生写入 | + +运行核验使用独立测试身份和数据库，不经过真实用户登录或外部账号开通流程；测试项目已清理，临时 API Key 已撤销。最初启动未先确认数据库可用，导致连接失败；补齐数据库启动和发布后，实际 HTTP smoke 通过，无需修改业务代码。 + +未验证：真实用户登录/发放 API Key 全流程、付费 Provider 生成、外部 MCP 客户端对 oneOf 参数的展示与使用、远端部署。本地验收不代表这些项目已通过。 + ## 6. 核对入口 - [External v1 OpenAPI](../openapi/genarrative-external-v1.openapi.json)：operation、参数、请求体、响应与公开字段权威。