Nacos MCP Server 治理迁移完全指南：AI 资源生命周期托管与兼容性规范

Nacos MCP Server 治理迁移完全指南：AI 资源生命周期托管与兼容性规范

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos

导读

本文档是 Nacos AI Registry 对 MCP（Model Context Protocol）Server 资源的治理契约规范，定义了 MCP 管理身份与版本治理如何迁移到统一的 AI 资源生命周期体系，同时完整保留既有 MCP 服务与发现数据面。读完本文，你将掌握 Nacos 中 MCP 资源的规范身份模型（namespaceId + type=mcp + mcpName）、SYNCING与LIFECYCLE_MANAGED两种管理路由状态、版本存储描述符与分层边界、标准生命周期 API 路由、历史mcpId的兼容解析规则，以及一次性的历史数据对账与托管切换（cutover）机制，并能在实际部署中区分"管理面迁移"与"数据面保持不变"的边界。

1. 范围与契约状态：一次只迁移管理面

本次迁移的第一步将 MCP 的管理身份与版本治理托管进公共 AI 资源生命周期，同时保持现有 MCP 服务与发现平面不变。管理路由存在两种状态：

需要特别强调的是，LIFECYCLE_MANAGED不是数据面切换（data-plane cutover）。它不会把历史 Manifest、Config 对象、直连服务（Direct Services）、普通服务引用（Service references）或客户端自有的 Runtime Services 变成可废弃的投影（disposable projections）。

管理路由的选择是按请求、针对完整操作契约一次性解析的。一个节点绝不能把读操作路由到生命周期行、却把写操作路由到历史实现，也不得暴露任何其他混合权威（mixed-authority）的组合。从源码结构看，这一约束由 McpCompatibilityMode.java 定义的SYNCING/LIFECYCLE_MANAGED枚举，以及 McpCompatibilityOperationService.java 中"每次请求解析一次完整操作契约"的McpCompatibilityModeResolver来落实。

以下变更被明确排除在本迁移之外，需要单独的兼容性设计与消费方迁移窗口：

• 增加内部McpEndpointKind或DIRECT/SERVICE_REF/RUNTIME_REF持久化模型；
• 将直连端点地址物化进 Version Server Config；
• 用无版本（versionless）Service 替换当前按版本（version-scoped）的 Runtime Service；
• 增加supportedTransports、versionRange或基于范围的 MCP Runtime 绑定；
• 退役直连持久化 Naming Services 或历史 Manifest；
• 改变前端/后端、订阅、重连、redo 或心跳行为。

2. 事实所有权（Fact Ownership）：谁拥有什么

本次迁移使用以下所有权边界，明确划分"管理身份"与"服务数据"：

一句话概括：AI Resource 托管 MCP 管理生命周期，但不替换当前 MCP 服务或发现数据面。

3. 身份与 AI 资源映射

3.1 规范身份（Canonical Identity）

Nacos 的规范管理身份是：

namespaceId + type=mcp + name=mcpName

• mcpName区分大小写，作为身份字段不可变。
• MCP 线协议不定义公开的 MCP Server UUID；官方 MCP Registry 使用 registry 范围内的 name 与 Version 作为公开坐标。因此 Nacos 用自己的 Namespace 来限定mcpName，绝不可把运行时的serverInfo.name当作全局唯一或安全敏感的身份。

文档基于当前上游契约得出这一结论：MCP 协议 schema 只暴露实现名与版本而无 Server UUID；MCP Tools 规范声明自报的 server name 在不同 Server 之间不保证唯一；官方 Registry API 与迁移 009 移除了早期 UUID 列，改用自然的 server-name + Version 键。

历史 UUID 形态的mcpId仅是内部物理存储别名与废弃兼容字段，不参与规范身份、鉴权、可见性、labels、搜索文档身份或运行时 Naming 身份。其 schema-version-1 的 Resource 扩展为：

{ "schemaVersion": 1, "mcpId": "4d7939c0-72ea-4ef4-b232-418d1e16b45c" }

机器可读契约见 mcp-resource-ext.schema.json。该 schema 明确mcpId的格式为^[0-9A-Fa-f]{8}-...（标准 UUID 形态），并声明它"不参与规范身份、鉴权、可见性、labels、搜索身份或运行时 Naming 身份"。从源码结构看，McpResourceExt.java 与 McpResourceExtSerializer.java 负责该扩展在ai_resource.ext中的序列化契约。

3.2 资源映射（Resource Mapping）

Resource 行按如下方式映射 MCP 字段：

唯一性约束：在一个 Namespace 内，一个mcpName只能有一个有效的type=mcpResource。由于当前物理唯一性包含from，对账必须检测多个同名来源行并阻止完成（block completion），而不能静默选择其中一个。

3.3 版本映射（Version Mapping）

每个 MCP 版本对应一个AiResourceVersion行，精确身份为：

namespaceId + type=mcp + mcpName + version

• 历史已发布版本以online状态进入生命周期；新管理 API 使用公共的draft、reviewing、reviewed、online、offline状态。
• 版本字符串保持不变；非 SemVer 的历史值在共享 Version 字段限制内仍是合法的精确身份。本迁移不引入 MCP 版本范围（version ranges）。

运行时查询仍只暴露已启用 Resource + 在线（online）Version。省略 Version 时，查询解析服务端管理的latest标签；管理读取则可以检查所有生命周期状态。

latest选择遵循公共生命周期，并带有如下 MCP 兼容细化：

• 标准发布、强制发布与 online 操作把latest移到目标版本；
• 历史直连 online 更新可在其既有 latest 参数要求时保留当前有效指针；
• 删除或下线当前 latest 时，先选剩余在线版本中最大的 SemVer，其次最大数值vN，再次最大稳定的区分大小写字符串；若没有在线版本剩余，则移除latest。

4. 物理内容与存储边界

4.1 保留的坐标（Preserved Coordinates）

迁移保留以下 Config 分组与 data id：

历史对账只创建指针：不得复制、移动、重写或扩展 Server/Tools/Resources 载荷字节，也不得改动任何 Naming Service 或实例。Manifest 仍是客户端与网关直接读 Config/Naming 时的兼容服务索引，不是规范管理身份或生命周期存储。

4.2 版本存储描述符（Version Storage Descriptor）

AiResourceVersion.storage包含一个 schema-version-1 描述符：

{ "provider": "nacos_config", "keyFormat": "mcp-config-v1", "serverKey": "public:mcp-server:<mcpId>-<version>-mcp-server.json", "toolKey": "public:mcp-tools:<mcpId>-<version>-mcp-tools.json", "resourceKey": "public:mcp-resources:<mcpId>-<version>-mcp-resources.json", "schemaVersion": 1 }

• serverKey必填；toolKey与resourceKey在对应内容缺失时省略（而非序列化为 null）。
• 内置 provider 只按前两个:分隔符拆分，其余部分视为 Config data id；它只接受上述三个 MCP 自有分组，绝不能变成对用户 Config 的任意namespace:group:dataId访问。
• 所有 key 都使用 Version 行中持久化的 provider。初始迁移只支持nacos_config；为其他 AI Storage provider 设计多对象 MCP 格式需要单独设计。

机器可读契约见 mcp-version-storage.schema.json。从源码结构看，McpVersionStorageService.java 是这一边界的所有者实现：它只拥有内容字节（"This component owns content bytes only"），Resource/Version 行、生命周期状态与兼容投影属于编排职责；其save()按"先 Tools/Resources 后 Server"的依赖顺序保存，deleteObsolete()则按 Resources→Tools→Server 依赖顺序清理被替换的旧对象，provider 与 key 未变化的对象会被保留。这从代码上印证了"载荷字节不被复制或重写"的契约。

4.3 必需的分层（Required Layering）

迁移可复用历史模型转换、JSON 处理、Manifest 选择、端点与 Naming 逻辑，但必须把物理 Config 访问移到如下边界之后：

MCP lifecycle/application service -> MCP Version Storage / MCP Serving Manifest Storage -> AI Resource Storage router or Config implementation

规范性规则：

• MCP Version Storage 通过 Version 行中持久化的描述符加载、保存、删除 Server、可选 Tools 与可选 Resources；
• MCP Serving Manifest Storage 封装mcp-server-versions的读取、发布与删除——Manifest 是服务兼容索引，不是身份解析器；
• MCP 生命周期与操作服务不得直接对四个 MCP Config 分组调用 Config CRUD；
• 服务不得接受mcpId、拼装 data id 从而绕过持久化 Version 描述符；
• Direct、REF 与客户端 Runtime Naming 状态不进入通用AiResourceStorageSPI；MCP 特有的所有权清理参与公共生命周期删除流程。

文档的结论很明确：保留 Config 与 Naming 意味着保留物理兼容性，而不是保留"服务直连 Config"这种分层违规。

5. 端点与服务兼容（Endpoint And Serving Compatibility）

公开端点模型与当前解析算法保持不变：

1. frontEndpointConfigList决定向前端调用方返回哪种前端端点形态；
2. 直连固定地址仍由当前按版本的持久化 Naming Service 与实例表示；Server Config 保留其当前serviceRef；
3. REF 继续读取由serviceRef选择的普通 Naming Service；Nacos MCP 不拥有该 Service 或其实例；
4. BACKEND前端条目继续直接使用解析出的后端端点；
5. 网关代理场景中，网关是前端，而remoteServerConfig.serviceRef仍选择真实后端；
6. 客户端 API 端点注册继续使用当前按版本的 Runtime Service、cluster 与实例元数据；
7. subscribeMcpServer继续轮询完整的 MCP 查询投影，而非直接订阅底层 Naming Service。

直连持久化 Service 是当前 MCP 数据与外部消费方契约，不是降级投影。下线（offline）只是把 Version 从服务 Manifest 中移除，但保留其内容与直连 Service，以便之后再次上线。

已知的网关集成（包括 Higress 与基于 Istio 的网关）可以直接读服务平面而不调用 MCP 专用查询 API，其兼容流程为：

1. 列出mcp-server-versionsConfig 条目；
2. 读取并 watch<mcpId>-mcp-versions.json；
3. 依据已发布 Version 拼出精确的 Server 与 Tools data id；
4. 读取remoteServerConfig.serviceRef；
5. 查询或订阅被引用的 Naming Service；
6. 构建网关前端路由，同时保留被引用的后端。

因此，生命周期托管不得要求这些消费方为保住既有发现能力而去协商新的 Nacos 能力（ability）或发布新版本。

6. 生命周期与兼容 Facades

6.1 标准管理生命周期（Standard Management Lifecycle）

MCP 使用公共的 draft、submit、review、publish、force-publish、redraft、online、offline、label、delete 规则。已发布内容通过标准生命周期 API 是不可变的；修改它需要创建新版本或走允许的 redraft 转换。

• Admin 前缀：/v3/admin/ai/mcp；Console 镜像：/v3/console/ai/mcp。精确路由见 v3-api-surface.md 第 9 节。
• 这些标准路由仅在管理权威到达LIFECYCLE_MANAGED后启用；在此之前合法请求会以RESOURCE_CONFLICT失败且不修改遗留 MCP 状态（见 McpCompatibilityOperationService.java 中 "MCP standard lifecycle APIs are unavailable before LIFECYCLE_MANAGED cutover" 的守卫逻辑）。
• 内嵌与独立 Console 直接使用同一应用服务；纯 Console 远程部署必须使用类型化的 Maintainer 版本管理传输，不得回退到遗留写路径（远程模式下这些新路由返回API_FUNCTION_DISABLED）。

两个内置 Console 前端在本发布窗口有意的兼容角色不同：

• 遗留console-ui留在历史直连 online 的创建/更新路由上；
• console-ui-next只通过标准生命周期路由创建或替换 draft，并暴露针对所选精确 Version 的合法 submit、publish、force-publish、redraft、online、offline、draft-delete、label 与可见性动作；在LIFECYCLE_MANAGED之前，下一代 UI 可保留历史读取用于诊断，但必须禁用生命周期变更，且不得回退到历史写。

console-ui-next的版本详情页展示可复制的 MCP 客户端配置，而非复制内部 Server/Tools/Resources 定义：远程 Server 使用与兼容 UI 相同的前端优先端点选择，避免混淆网关前端与实际后端地址；stdio Server 则把本地或 Package 启动配置包装进标准mcpServers对象。

Maintainer 服务契约：McpMaintainerService暴露带显式 namespace 与默认 namespace 重载的版本管理方法。新 draft 创建与替换复用既有createMcpServer/updateMcpServer名称（通过McpServerDraftRequest重载）；精确读取用listMcpServerVersions/getMcpServerVersion；精确版本转换用McpServerVersionCommand；标签替换用McpServerLabelsUpdateRequest。这些模型不携带顶层namespaceId或mcpId选择器——namespace 是独立的方法参数，规范资源身份是mcpName。历史McpServerBasicInfo载荷内部的id/namespaceId仅是兼容内容，服务在身份解析时忽略它们。

从源码结构看，McpLifecycleOperationService.java 正是上述生命周期操作的实现主体，而 McpOperationService.java 定义了createMcpServer等稳定接口；McpCompatibilityOperationService.java 则按模式解析后把调用路由到legacy()或managed()实现。

遗留 Maintainer 详情与直连 online 创建/更新方法自 3.3.0 起废弃，计划在 4.0.0 移除，其 Javadoc 必须指明精确的类型化版本读取或 draft-submit-publish 替代。跨资源 list/search 与已发布版本或全资源删除不在此次废弃范围内，直到等价生命周期操作定义完毕。

Pipeline 集成：submit 构建一个 resource type 为MCP的ResourceFilesPipelineContext，携带被保留的 Server、可选 Tools、可选 Resources 载荷。若没有启用且支持 MCP 的 Pipeline 节点，submit 走公共直接发布路径；否则版本进入reviewing，批准或拒绝回调把它移到reviewed，且只有显式批准的 publish 才更新 online 生命周期状态与兼容 Manifest。force-publish 是经过审计的 Pipeline 旁路（bypass）。版本摘要与精确版本详情暴露 Version 行可选的publishPipelineInfo，管理客户端用它区分"批准"与"拒绝"的评审——因为两种结果的 Version 状态都是reviewed。console-ui-next只在当前 Pipeline 结果为REJECTED时对全局管理员展示 force-publish，且 redraft 后被标记为historical的拒绝结果不能授权 force-publish。

6.2 历史直连 Facades（Historical Direct-Online Facades）

既有 Admin、Console、Maintainer SDK、Java Client SDK 与 gRPC 线格式保持兼容，并映射到生命周期应用服务：

同版本覆盖是被审计的兼容例外，标准生命周期 API 绝不复用。带isPublish=false的兼容覆盖必须保留当前 Version 生命周期状态、Manifest 展示、latest 指针与既有发布元数据；被覆盖的版本内容只有在之后显式 publish 后才成为已发布展示。兼容直连 online 创建可临时把 Resource 的editingVersion指针用作进行中重试标记，且仅在 Manifest 被重读并验证后清除该指针。

6.3 Draft 与发布顺序（Draft And Publish Ordering）

Draft 写入顺序：

1. 解析或生成内部mcpId；
2. 通过 MCP Version Storage 保存 Server 与可选 Tools/Resources；
3. 用相同描述符创建或更新draftVersion 行；
4. 更新 Resource 工作指针。

Draft不会被加入历史 Manifest。删除精确 draft 的顺序：先 MCP Storage 清理 → 清理成功后移除 Version 行 → 最后清除匹配的 Resource 工作指针。保留的指针是存储或行删除被中断时的重试锚点；行已被移除后的重试会直接清除指针，无需已删除内容的描述符。

发布或上线顺序：

1. 通过 MCP Version Storage 加载并校验版本内容；
2. 校验既有 Direct 或 REF 端点事实（不重写它们）；
3. 转换 Version 状态并更新服务端管理标签；
4. 依据完整在线版本集合重建兼容 Manifest；
5. 最后通过 MCP Serving Manifest Storage 发布 Manifest；
6. 返回成功前重读并验证服务视图。

online 生命周期行是持久的期望状态。若 Manifest 发布或验证失败，操作报告失败但保留该行；幂等重试或托管 reconciler 重建缺失的服务投影。搜索索引只在业务变更之后被调度，绝不决定发布成功与否。

6.4 下线与删除（Offline And Delete）

下线：先把 Version 收敛到持久的offline生命周期状态，再重建并验证不含该版本的 Manifest 服务视图。它不会隐式禁用 Resource，且保留 Server/Tools/Resources 内容与直连持久化 Service。若 Manifest 收敛失败，操作报告失败，而保留的 offline 行给重试与对账一个无歧义目标。

版本删除（6 步）：

1. 加载并保留 Version 存储描述符；
2. 把 Version 收敛到offline，修复标签，移除并验证其 Manifest 暴露；
3. 调用该 Version 自有的直连状态 MCP 专用清理钩子；
4. 通过 MCP Version Storage 删除 Server/Tools/Resources；
5. 仅在所有物理清理成功后删除 Version 行；
6. 调度异步 Search 维护。

全资源删除（6 步）：

1. 按名称或废弃兼容 ID 解析并鉴权规范 Resource，加载每个 Version 描述符；
2. 禁用 Resource 并把其 Versions 收敛到offline，使生命周期行持久表达"不服务"目标；
3. 删除并验证服务 Manifest，使网关停止发现它；
4. 调用带 MCP 存储 deleter 的公共 Resource-with-Versions 删除流程；
5. 对每个 Version，deleter 校验描述符、清理 MCP 自有的直连状态，并通过 Storage 删除 Resources/Tools/Server 内容；
6. 仅在每个回调成功后移除 Resource 与 Version 行。

任何 Manifest、端点或内容清理失败都会报告失败，并保留 disabled/offline 的 Resource 与 Version 行以及重试所需的存储描述符。这些生命周期状态本身就是持久的恢复意图，因此不需要单独的 MCP 操作日志或 Manifest 墓碑（tombstone）。仅 ID 的重试仍通过AiResource.ext解析。普通 REF Service 与客户端自有的 Runtime 实例保留既有所有权，不会随 MCP 版本被删除。

7. 废弃mcpId兼容

7.1 受支持用途

mcpId仍用于：

• 拼装既有 Config data id；
• 让 Version 与 Manifest Storage 定位历史 Config；
• 保留既有 Admin、Console、Maintainer、Client 模型、事件与响应形态；
• 保留直接读 Config/Naming 的消费方。

它不得成为新 API、Search 文档、鉴权规则、可见性规则、标签或生命周期操作的身份。

7.2 管理解析（Management Resolution）

新生命周期 API 接受namespaceId + mcpName (+ version)，不新增mcpId参数。既有已接受纯 ID 输入的 Admin、Console、Maintainer HTTP 路径保持兼容，解析规则为：

• 仅名称：按 Namespace、type=mcp、name 做精确AiResource查找；
• 名称加 ID：做精确名称查找并校验ext.mcpId匹配；
• 仅 ID：分页当前 Namespace 的type=mcpResource 行，解析ext.mcpId，要求恰好一个匹配；
• 缺失、畸形、重复或冲突的别名返回受控的参数或完整性错误。

鉴权顺序：协议过滤器先用既有线契约鉴权请求。对于仅 ID 输入，生命周期定位器先解析规范 Resource，并在任何内容读取或变更之前，针对该精确规范名称重复身份与权威校验；后续路径与基于名称的输入走相同的可见性与生命周期操作。这一顺序避免未鉴权的别名枚举，同时防止空的线名称绕过规范鉴权。ID 查找不得查询 Search 索引、Manifest、Config 或历史 MCP 内存索引，也不为该低频废弃路径引入新表、新列或新 JSON 索引。SYNCING期间历史索引可继续服务纯历史管理路径；LIFECYCLE_MANAGED之后没有任何管理正确性路径依赖它。

既有创建/发布响应与既有 DTO 继续返回 ID 字段。移除mcpId需要后续迁移物理 Config 坐标与直连消费方；本阶段只废弃、不授权移除。

7.3 gRPC 字段区分

三个线字段的兼容状态不同：

1. 顶层AbstractMcpRequest.mcpId（被压平进当前 MCP 请求）：保持忽略与废弃，处理器不增加 ID 查找，保留当前 name 要求；
2. 嵌套McpServerBasicInfo.id：在当前请求使用它的地方仍是活跃兼容输入或模型字段，name/ID 输入必须一致；
3. ReleaseMcpServerResponse.mcpId：仍是活跃兼容输出。

字段号与线形态不变。SDK-proto 变更可单独为休眠的顶层字段加废弃选项，但生命周期迁移不依赖该发布。

8. 历史对账与托管切换（Historical Reconciliation And Managed Cutover）

8.1 标记与租约（Marker And Lease）

没有操作者选择存储模式。单向管理完成标记是内部 Config 对象：

group = nacos_internal dataId = nacos.ai.mcp.resource.migration.v1 content = {"schemaVersion":1,"state":"LIFECYCLE_MANAGED","completedAt":<epochMillis>}

• 永久标记意味着管理行被完全托管，但它不授权删除或变更服务 Config 或 Naming 数据。
• 可续租的集群租约使用nacos.ai.mcp.resource.reconciliation.lease.v1。
• 系统仍在同步时，任务可在nacos.ai.mcp.resource.reconciliation.progress.v1持久化非权威诊断，state=SYNCING。这两个对象都不是完成标记。失去租约只会停止当前写者，不会删除 MCP 内容。

从源码结构看，McpLifecycleManagementStateService.java 持有nacos.ai.mcp.resource.migration.v1常量与LIFECYCLE_MANAGED_STATE，负责标记的持久化与模式解析（resolveMode()返回LIFECYCLE_MANAGED或SYNCING）。

8.2 对账（Reconciliation）

根ApplicationReadyEvent之后，后台任务：

1. 获取并续租集群租约；
2. 分页每个 Namespace，通过 Manifest Storage 扫描mcp-server-versions（而非只信任内存 MCP 索引）；
3. 通过 Version Storage 校验 Server、可选 Tools、可选 Resources；
4. 幂等地把每个历史 Version upsert 为online，带指向既有内容的描述符；
5. 最后 upsert Resource（name、内部 ID、启用状态、latest、在线数、from=legacy-mcp）；
6. 按规范mcpName调度共享异步 Search 对账；
7. 检测缺失内容、身份冲突、重复来源行、非法 Version 与待删除项；
8. 把被移除的legacy-mcp行路由进公共生命周期删除/恢复流程，不删除独立创建的资源；
9. 完成一轮零差异（zero-difference）校验；
10. 仅在所有已知集群成员都支持托管写与 write-after-reconcile 钩子后写完成标记。

Version/Resource upsert 阶段只创建指针：绝不保存或重写历史载荷，绝不改动 Naming。在规范名称 Search projector 与公共生命周期删除/恢复处理器在所有成员可用之前，SYNCINGreconciler 把 Search 回填、多余 Version、孤立legacy-mcp工作记录为阻塞诊断，不得入队 ID 键的 Search 任务或直接删除 Resource/Version 行、载荷 Config 或 Naming 状态——这种部分同步永远无法写完成标记。在名称键 projector 引入前，即使生命周期行零差异，进度记录也保持searchBackfillPending=true、managedCutoverReady=false。

从源码结构看，McpHistoricalResourceReconciler.java 是对账任务载体，McpResourceLocator.java 承担规范身份解析。

8.3SYNCING期间的写入

SYNCING期间历史管理响应保持完全历史化，部分 Resource 行不作为管理权威暴露。有能力的节点通过 MCP Storage 执行当前物理兼容写，然后调用相同的 per-Resource reconciler；周期扫描修复来自旧节点的写入。新生命周期写 API 在托管切换前不开放；混合版本集群保持SYNCING。

• 生命周期对账在此状态是次级收敛步骤：其失败由周期扫描诊断修复，但不会重新解释或回滚一次已成功的历史权威写。
• 兼容 facade 在此状态把完整读/写操作契约路由到历史实现；永久标记只在每个托管操作及其恢复路径都可用后才把完整契约切到生命周期实现，绝不逐个方法单独切换。

切换（cutover）要求：

• 每个历史 Manifest 恰好有一个等价 Resource；
• 每个历史 Version 有等价 Version 行与正确描述符；
• name、内部 ID、启用状态、latest、在线数与 Version 集合一致；
• 无重复来源行、缺失内容、身份冲突或待删除项；
• 一轮最终零差异校验；
• 每个集群成员支持 MCP Storage、生命周期 facades、write-after-reconcile 与规范名称 Search 任务；
• 无托管 MCP 服务路径绕过 Storage 直连 Config CRUD。

外部网关不参与此能力门控，因为其服务契约不变。标记永久且不会自动回滚；标记存在后，缺乏托管写能力的 Nacos 成员不得服务 MCP 管理流量，因为未挂钩的历史写可能使生命周期行发散。该限制不对外部 Config/Naming 消费方产生新的协商要求。

9. 搜索、导入与适配器规则

MCP 通过一个共享索引与 Query Planner参与通用 AI 资源搜索与 MCP 专用搜索 facade。规范搜索resourceName是mcpName，绝不是mcpId。

• MCP Search projector 遵循与管理流量相同的完整兼容操作路由器：SYNCING时通过 MCP Storage 按规范名称投影完整历史视图，使部分对账的 Resource 行无法隐藏 MCP Servers；LIFECYCLE_MANAGED后同一路由器通过持久化存储描述符加载可见 Resource、online Version 与内容。projector 输入与搜索身份绝不使用mcpId。
• 可投影公开描述、Tools、Resources、标签、协议与能力。凭证、运行时实例与敏感鉴权元数据绝不进入 Search 块。
• 每次成功的 create、update、publish、online、offline、delete、enable/disable、label 或 import 变更都会按namespaceId + type=mcp + mcpName调度持久异步维护任务；任务可合并连续更新并重试失败。业务请求不等待索引完成。最终一致的 Search 状态绝不用于身份解析、鉴权、可见性或写正确性。
• 历史回填重建名称键文档；投影版本对账与孤立清理移除历史 ID 键文档与任务，系统不得保留两个规范搜索身份。

外部导入使用 ai-resource-import-plugin-spec.md：插件产出 artifacts，绝不直接写 MCP 存储；MCP 资源操作符通过生命周期应用服务与 MCP Storage 应用 artifacts，同时保留既有 Manifest、Config 与 Naming 服务输出。

Console 专用的GET /v3/console/ai/mcp/importToolsFromMcp辅助接口保留其既有出站网络策略：操作者可禁用（nacos.console.ai.mcp.import.enabled），私有或本地目标需要操作者 IP/CIDR 白名单（nacos.console.ai.mcp.import.allowed-private-addresses），端点不能覆盖baseUrl来源，且禁用重定向。可选 AI Registry 适配器保留外部响应形态，本管理迁移不要求适配器消费方协商新版本。

10. API 与 SDK 边界

第一步迁移改变管理实现，之后新增标准管理生命周期操作：

• Admin 与 Console历史方法保留请求、响应、错误与直连 online 兼容语义，同时进入同一生命周期服务；
• Maintainer SDK二进制签名与历史重载保持兼容；类型化 name/Version 生命周期方法可按标准 Admin 语义新增；
• 导入收敛到生命周期服务与 MCP Storage；
• 遗留 Console UI保留直连 online 兼容流程；下一代 Console UI在对应 API 可用后只使用生命周期变更，权威仍为SYNCING时保持只读。

本次迁移不改变：

• Java ClientAiService的 MCP 公开接口；
• Query、Release 或 Endpoint 的 gRPC 线布局与字段号；
• 客户端端点注册/注销、订阅、重连、redo 或心跳；
• 当前 Runtime Service 名称、集群或元数据；
• MCP Client HTTP API；
• AI Registry 适配器响应形态。

Client HTTP 与 gRPC 的对齐、以及复用 Agent HTTP publisher 心跳/续期，属于独立的后续工作。

11. 工具 Schema 兼容（Tool Schema Compatibility）

MCP 工具的outputSchema是 JSON Schema。Nacos 保留合法的类型联合（type unions），例如可空属性{"type":["string","null"]}。Console 的 load/save 与 OpenAPI 导入不得把该联合窄化为单一 string 类型。

12. 必需的验证项（Required Verification）

实现 PR 至少必须覆盖：

• 精确的 Resource 与 Version 映射，包括历史非 SemVer 版本字符串；
• name-only、name-plus-ID 与遗留 ID-only 的 Resource 行解析、协议鉴权后对 ID-only 输入的精确规范再鉴权、冲突处理；
• Manifest/Server/Tools/Resources 坐标与字节不变；
• 对账期间无 Naming 变更，Direct、REF、前端/后端、Runtime、订阅、重连与 redo 行为不变；
• 所有 Server/Tools/Resources 与 Manifest Config 访问都经过 MCP Storage 而非直接服务 Config CRUD；
• draft→publish 生命周期、历史同版本覆盖隔离、latest 选择与 Manifest-last 发布恢复；
• 下线保留内容与直连 Service；
• 版本与全资源删除、物理清理失败时的公共行保留、Manifest 移除后按废弃 ID 重试、不删除普通 REF 或客户端 Runtime 状态；
• 幂等异步对账、租约接管、混合成员门控、零差异完成、重启与LIFECYCLE_MANAGED持久化；
• 规范名称键异步搜索、失败重试、回填与历史 ID 键孤立清理；
• 等价的 Admin、Console、Maintainer、Client、Import、Search 与适配器兼容投影；
• 既有 MCP Java Client 行为覆盖下的默认 JSON 与 Jackson 3 两种客户端适配器。

异步断言使用对公共行为的有界轮询，不得依赖固定 sleep、内部任务顺序或最终一致 Search 来做身份正确性判断。

13. 推迟的演进（Deferred Evolution）

以下内容需要后续独立设计：

• MCP Client HTTP 的 query、release、endpoint、subscription 与 heartbeat/renewal 对齐；
• 端点种类持久化与直连端点物化；
• 历史 Manifest 或直连 Services 的退役或版本协商；
• 无版本 Runtime 发布、多传输元数据与 SemVer 范围绑定；
• 非 Config 的多对象 MCP 存储；
• 移除废弃的物理mcpId别名。

上游 MCP 的 tool、resource、transport、auth 与 Registry 格式可能演进。此类变更必须保留 Nacos 身份与所有权边界，或发布明确的 schema 与迁移修订。

结语：一句话记住迁移边界

本规范的灵魂在于严格分离"管理面"与"数据面"：管理身份与版本治理迁入ai_resource/ai_resource_version生命周期，而 Manifest、Config、Naming 服务平面原样保留；SYNCING期间历史实现权威、生命周期行只做收敛对账，完成零差异校验并确认全员能力后，才由内部 Config 标记一次性切换到LIFECYCLE_MANAGED。对运行者与网关消费方而言，唯一需要关心的是：对外服务契约从头到尾没有变化。

【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos