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 对 MCPModel Context ProtocolServer 资源的治理契约规范定义了 MCP 管理身份与版本治理如何迁移到统一的 AI 资源生命周期体系同时完整保留既有 MCP 服务与发现数据面。读完本文你将掌握 Nacos 中 MCP 资源的规范身份模型namespaceId typemcp mcpName、SYNCING与LIFECYCLE_MANAGED两种管理路由状态、版本存储描述符与分层边界、标准生命周期 API 路由、历史mcpId的兼容解析规则以及一次性的历史数据对账与托管切换cutover机制并能在实际部署中区分管理面迁移与数据面保持不变的边界。1. 范围与契约状态一次只迁移管理面本次迁移的第一步将 MCP 的管理身份与版本治理托管进公共 AI 资源生命周期同时保持现有 MCP 服务与发现平面不变。管理路由存在两种状态状态管理路由客户端与网关服务路由SYNCING历史 MCP 管理保持权威同时进行 Resource 与 Version 行的对账reconcile。现有 Manifest、Config 与 Naming 行为不变。LIFECYCLE_MANAGED完整的兼容管理操作集合使用公共 AI 资源生命周期进行读写。现有 Manifest、Config 与 Naming 行为保持原样。需要特别强调的是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用无版本versionlessService 替换当前按版本version-scoped的 Runtime Service增加supportedTransports、versionRange或基于范围的 MCP Runtime 绑定退役直连持久化 Naming Services 或历史 Manifest改变前端/后端、订阅、重连、redo 或心跳行为。2. 事实所有权Fact Ownership谁拥有什么本次迁移使用以下所有权边界明确划分管理身份与服务数据事实所有者契约MCP 管理身份ai_resourcenamespaceId typemcp mcpName启用状态、owner、scope、labels、工作版本指针ai_resource公共 AI 资源元数据与生命周期事实版本状态、作者、Pipeline 状态、内容指针ai_resource_version公共 AI 资源版本事实Server、Tools、Resources 载荷既有 MCP Config 对象坐标与字节被保留已发布版本集合与历史最新视图mcp-server-versionsManifest持续维护的兼容服务索引直连端点地址既有持久化 Naming Service 与实例当前直连端点事实非降级投影普通 REF 后端由serviceRef选择的用户自有 Naming ServiceMCP 只读不拥有被引用 Service前端/后端映射既有 Server Config 与端点查询逻辑frontEndpointConfigList行为不变客户端 Runtime 端点客户端自有的 Naming 状态Service 名、cluster、metadata、redo、liveness 不变搜索身份与索引维护mcpName与共享异步索引服务搜索最终一致永不为身份来源一句话概括AI Resource 托管 MCP 管理生命周期但不替换当前 MCP 服务或发现数据面。3. 身份与 AI 资源映射3.1 规范身份Canonical IdentityNacos 的规范管理身份是namespaceId typemcp namemcpNamemcpName区分大小写作为身份字段不可变。MCP 线协议不定义公开的 MCP Server UUID官方 MCP Registry 使用 registry 范围内的 name 与 Version 作为公开坐标。因此 Nacos 用自己的 Namespace 来限定mcpName绝不可把运行时的serverInfo.name当作全局唯一或安全敏感的身份。文档基于当前上游契约得出这一结论MCP 协议 schema 只暴露实现名与版本而无 Server UUIDMCP 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 MappingResource 行按如下方式映射 MCP 字段AiResource字段MCP 映射namespaceId、type、nameNamespace、常量mcp、mcpNamedescMCP 描述status历史enabledtrue映射为enable否则为disableowner创建或导入的操作者历史对账使用nacosscope新资源的默认可见性历史对账使用PUBLICbizTags公开的 MCP 业务标签或空集合ext包含内部mcpId别名的McpResourceExtfrom本地创建、导入来源或legacy-mcp对账来源versionInfo标准的编辑、评审、在线数与标签汇总唯一性约束在一个 Namespace 内一个mcpName只能有一个有效的typemcpResource。由于当前物理唯一性包含from对账必须检测多个同名来源行并阻止完成block completion而不能静默选择其中一个。3.3 版本映射Version Mapping每个 MCP 版本对应一个AiResourceVersion行精确身份为namespaceId typemcp mcpName version历史已发布版本以online状态进入生命周期新管理 API 使用公共的draft、reviewing、reviewed、online、offline状态。版本字符串保持不变非 SemVer 的历史值在共享 Version 字段限制内仍是合法的精确身份。本迁移不引入 MCP 版本范围version ranges。运行时查询仍只暴露已启用 Resource 在线onlineVersion。省略 Version 时查询解析服务端管理的latest标签管理读取则可以检查所有生命周期状态。latest选择遵循公共生命周期并带有如下 MCP 兼容细化标准发布、强制发布与 online 操作把latest移到目标版本历史直连 online 更新可在其既有 latest 参数要求时保留当前有效指针删除或下线当前 latest 时先选剩余在线版本中最大的 SemVer其次最大数值vN再次最大稳定的区分大小写字符串若没有在线版本剩余则移除latest。4. 物理内容与存储边界4.1 保留的坐标Preserved Coordinates迁移保留以下 Config 分组与 data id内容Config 分组Data id已发布版本 Manifestmcp-server-versionsmcpId-mcp-versions.json版本 Servermcp-servermcpId-version-mcp-server.json版本 Toolsmcp-toolsmcpId-version-mcp-tools.json版本 Resourcesmcp-resourcesmcpId-version-mcp-resources.json历史对账只创建指针不得复制、移动、重写或扩展 Server/Tools/Resources 载荷字节也不得改动任何 Naming Service 或实例。Manifest 仍是客户端与网关直接读 Config/Naming 时的兼容服务索引不是规范管理身份或生命周期存储。4.2 版本存储描述符Version Storage DescriptorAiResourceVersion.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 onlyResource/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 与可选 ResourcesMCP Serving Manifest Storage 封装mcp-server-versions的读取、发布与删除——Manifest 是服务兼容索引不是身份解析器MCP 生命周期与操作服务不得直接对四个 MCP Config 分组调用 Config CRUD服务不得接受mcpId、拼装 data id 从而绕过持久化 Version 描述符Direct、REF 与客户端 Runtime Naming 状态不进入通用AiResourceStorageSPIMCP 特有的所有权清理参与公共生命周期删除流程。文档的结论很明确保留 Config 与 Naming 意味着保留物理兼容性而不是保留服务直连 Config这种分层违规。5. 端点与服务兼容Endpoint And Serving Compatibility公开端点模型与当前解析算法保持不变frontEndpointConfigList决定向前端调用方返回哪种前端端点形态直连固定地址仍由当前按版本的持久化 Naming Service 与实例表示Server Config 保留其当前serviceRefREF 继续读取由serviceRef选择的普通 Naming ServiceNacos MCP 不拥有该 Service 或其实例BACKEND前端条目继续直接使用解析出的后端端点网关代理场景中网关是前端而remoteServerConfig.serviceRef仍选择真实后端客户端 API 端点注册继续使用当前按版本的 Runtime Service、cluster 与实例元数据subscribeMcpServer继续轮询完整的 MCP 查询投影而非直接订阅底层 Naming Service。直连持久化 Service 是当前 MCP 数据与外部消费方契约不是降级投影。下线offline只是把 Version 从服务 Manifest 中移除但保留其内容与直连 Service以便之后再次上线。已知的网关集成包括 Higress 与基于 Istio 的网关可以直接读服务平面而不调用 MCP 专用查询 API其兼容流程为列出mcp-server-versionsConfig 条目读取并 watchmcpId-mcp-versions.json依据已发布 Version 拼出精确的 Server 与 Tools data id读取remoteServerConfig.serviceRef查询或订阅被引用的 Naming Service构建网关前端路由同时保留被引用的后端。因此生命周期托管不得要求这些消费方为保住既有发现能力而去协商新的 Nacos 能力ability或发布新版本。6. 生命周期与兼容 Facades6.1 标准管理生命周期Standard Management LifecycleMCP 使用公共的 draft、submit、review、publish、force-publish、redraft、online、offline、label、delete 规则。已发布内容通过标准生命周期 API 是不可变的修改它需要创建新版本或走允许的 redraft 转换。Admin 前缀/v3/admin/ai/mcpConsole 镜像/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 历史直连 FacadesHistorical Direct-Online Facades既有 Admin、Console、Maintainer SDK、Java Client SDK 与 gRPC 线格式保持兼容并映射到生命周期应用服务历史操作托管行为创建或发布 MCP创建 Resource 与 Version立即上线该版本按历史契约设置 latest返回历史响应形态用新版本更新创建 online Version 并应用历史 latest 参数更新既有精确版本通过 MCP Storage 做仅兼容的同版本覆盖same-Version overwrite保留生命周期状态与历史 latest 行为查询返回与迁移前相同的服务投影与响应形态删除精确版本停止 Manifest 暴露通过托管删除流程清理 MCP 自有的直连状态与版本内容再删除 Version 行删除 MCP停止 Manifest 暴露运行带 MCP 存储清理的公共Resource-with-Versions删除再移除元数据行同版本覆盖是被审计的兼容例外标准生命周期 API 绝不复用。带isPublishfalse的兼容覆盖必须保留当前 Version 生命周期状态、Manifest 展示、latest 指针与既有发布元数据被覆盖的版本内容只有在之后显式 publish 后才成为已发布展示。兼容直连 online 创建可临时把 Resource 的editingVersion指针用作进行中重试标记且仅在 Manifest 被重读并验证后清除该指针。6.3 Draft 与发布顺序Draft And Publish OrderingDraft 写入顺序解析或生成内部mcpId通过 MCP Version Storage 保存 Server 与可选 Tools/Resources用相同描述符创建或更新draftVersion 行更新 Resource 工作指针。Draft不会被加入历史 Manifest。删除精确 draft 的顺序先 MCP Storage 清理 → 清理成功后移除 Version 行 → 最后清除匹配的 Resource 工作指针。保留的指针是存储或行删除被中断时的重试锚点行已被移除后的重试会直接清除指针无需已删除内容的描述符。发布或上线顺序通过 MCP Version Storage 加载并校验版本内容校验既有 Direct 或 REF 端点事实不重写它们转换 Version 状态并更新服务端管理标签依据完整在线版本集合重建兼容 Manifest最后通过 MCP Serving Manifest Storage 发布 Manifest返回成功前重读并验证服务视图。online 生命周期行是持久的期望状态。若 Manifest 发布或验证失败操作报告失败但保留该行幂等重试或托管 reconciler 重建缺失的服务投影。搜索索引只在业务变更之后被调度绝不决定发布成功与否。6.4 下线与删除Offline And Delete下线先把 Version 收敛到持久的offline生命周期状态再重建并验证不含该版本的 Manifest 服务视图。它不会隐式禁用 Resource且保留 Server/Tools/Resources 内容与直连持久化 Service。若 Manifest 收敛失败操作报告失败而保留的 offline 行给重试与对账一个无歧义目标。版本删除6 步加载并保留 Version 存储描述符把 Version 收敛到offline修复标签移除并验证其 Manifest 暴露调用该 Version 自有的直连状态 MCP 专用清理钩子通过 MCP Version Storage 删除 Server/Tools/Resources仅在所有物理清理成功后删除 Version 行调度异步 Search 维护。全资源删除6 步按名称或废弃兼容 ID 解析并鉴权规范 Resource加载每个 Version 描述符禁用 Resource 并把其 Versions 收敛到offline使生命周期行持久表达不服务目标删除并验证服务 Manifest使网关停止发现它调用带 MCP 存储 deleter 的公共 Resource-with-Versions 删除流程对每个 Versiondeleter 校验描述符、清理 MCP 自有的直连状态并通过 Storage 删除 Resources/Tools/Server 内容仅在每个回调成功后移除 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、typemcp、name 做精确AiResource查找名称加 ID做精确名称查找并校验ext.mcpId匹配仅 ID分页当前 Namespace 的typemcpResource 行解析ext.mcpId要求恰好一个匹配缺失、畸形、重复或冲突的别名返回受控的参数或完整性错误。鉴权顺序协议过滤器先用既有线契约鉴权请求。对于仅 ID 输入生命周期定位器先解析规范 Resource并在任何内容读取或变更之前针对该精确规范名称重复身份与权威校验后续路径与基于名称的输入走相同的可见性与生命周期操作。这一顺序避免未鉴权的别名枚举同时防止空的线名称绕过规范鉴权。ID 查找不得查询 Search 索引、Manifest、Config 或历史 MCP 内存索引也不为该低频废弃路径引入新表、新列或新 JSON 索引。SYNCING期间历史索引可继续服务纯历史管理路径LIFECYCLE_MANAGED之后没有任何管理正确性路径依赖它。既有创建/发布响应与既有 DTO 继续返回 ID 字段。移除mcpId需要后续迁移物理 Config 坐标与直连消费方本阶段只废弃、不授权移除。7.3 gRPC 字段区分三个线字段的兼容状态不同顶层AbstractMcpRequest.mcpId被压平进当前 MCP 请求保持忽略与废弃处理器不增加 ID 查找保留当前 name 要求嵌套McpServerBasicInfo.id在当前请求使用它的地方仍是活跃兼容输入或模型字段name/ID 输入必须一致ReleaseMcpServerResponse.mcpId仍是活跃兼容输出。字段号与线形态不变。SDK-proto 变更可单独为休眠的顶层字段加废弃选项但生命周期迁移不依赖该发布。8. 历史对账与托管切换Historical Reconciliation And Managed Cutover8.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持久化非权威诊断stateSYNCING。这两个对象都不是完成标记。失去租约只会停止当前写者不会删除 MCP 内容。从源码结构看McpLifecycleManagementStateService.java 持有nacos.ai.mcp.resource.migration.v1常量与LIFECYCLE_MANAGED_STATE负责标记的持久化与模式解析resolveMode()返回LIFECYCLE_MANAGED或SYNCING。8.2 对账Reconciliation根ApplicationReadyEvent之后后台任务获取并续租集群租约分页每个 Namespace通过 Manifest Storage 扫描mcp-server-versions而非只信任内存 MCP 索引通过 Version Storage 校验 Server、可选 Tools、可选 Resources幂等地把每个历史 Version upsert 为online带指向既有内容的描述符最后 upsert Resourcename、内部 ID、启用状态、latest、在线数、fromlegacy-mcp按规范mcpName调度共享异步 Search 对账检测缺失内容、身份冲突、重复来源行、非法 Version 与待删除项把被移除的legacy-mcp行路由进公共生命周期删除/恢复流程不删除独立创建的资源完成一轮零差异zero-difference校验仅在所有已知集群成员都支持托管写与 write-after-reconcile 钩子后写完成标记。Version/Resource upsert 阶段只创建指针绝不保存或重写历史载荷绝不改动 Naming。在规范名称 Search projector 与公共生命周期删除/恢复处理器在所有成员可用之前SYNCINGreconciler 把 Search 回填、多余 Version、孤立legacy-mcp工作记录为阻塞诊断不得入队 ID 键的 Search 任务或直接删除 Resource/Version 行、载荷 Config 或 Naming 状态——这种部分同步永远无法写完成标记。在名称键 projector 引入前即使生命周期行零差异进度记录也保持searchBackfillPendingtrue、managedCutoverReadyfalse。从源码结构看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 ServersLIFECYCLE_MANAGED后同一路由器通过持久化存储描述符加载可见 Resource、online Version 与内容。projector 输入与搜索身份绝不使用mcpId。可投影公开描述、Tools、Resources、标签、协议与能力。凭证、运行时实例与敏感鉴权元数据绝不进入 Search 块。每次成功的 create、update、publish、online、offline、delete、enable/disable、label 或 import 变更都会按namespaceId typemcp 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 APIAI Registry 适配器响应形态。Client HTTP 与 gRPC 的对齐、以及复用 Agent HTTP publisher 心跳/续期属于独立的后续工作。11. 工具 Schema 兼容Tool Schema CompatibilityMCP 工具的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 CRUDdraft→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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考