AI Resource Import Plugin

AI Resource Import plugins convert MCP Servers, Skills, and future AI resources from external registries, marketplaces, or enterprise catalogs into artifacts that Nacos can validate and write. They own only the external protocol and conversion. Namespace, identity, auth, visibility, versioning, publish Pipeline, and storage remain AI Registry responsibilities.

Unified source model

ai-resource-import is a ROUTED plugin type. One Builder represents one fixed external source:

pluginId = ai-resource-import:{pluginName}
sourceId = managed pluginName

A request sourceId routes directly to one enabled Builder. The existing API field pluginName remains importer/protocol metadata for Console compatibility; it is not the managed plugin name.

sourceId
  -> AiResourceImportServiceBuilder(accepted snapshot)
  -> request-scoped AiResourceImportService
  -> AiResourceOperator(resourceType)

One pluginName represents exactly one source. Configuration can no longer clone one implementation to multiple endpoints. Ship another Builder with a distinct pluginName for another fixed source.

Gates, state, and defaults

When AI function mode and the AI module permit it, the family switch controls importer loading:

nacos.plugin.ai-resource-import.enabled=true

nacos.ai.resource.import.enabled is a historical alias. The standard key is authoritative whenever it is present, including when its value is blank. The family gate defaults to enabled even when neither key is configured; only an explicit false disables AI Resource Import. The distribution also sets the standard key to true.

Initial source state uses:

nacos.plugin.ai-resource-import.{pluginName}.enabled=true

Persisted unified state takes precedence. Runtime routing also checks Builder state; disabled sources are neither listed nor allowed to search, validate, or execute.

Four built-in sources

The Console still displays Official MCP Registry for mcp-official and skills.sh for skills-sh. The existing select, search, choose candidates, validate, and execute experience remains unchanged.

Fixed endpoint sources

mcp-official and skills-sh do not declare endpoint, allow-http, or allow-private-network and do not accept old endpoint overrides. The source endpoint is part of implementation identity.

nacos.plugin.ai-resource-import.mcp-official.enabled=true
nacos.plugin.ai-resource-import.skills-sh.enabled=true

Operator-configured endpoint sources

Enable an MCP Registry protocol endpoint:

nacos.plugin.ai-resource-import.mcp-registry-protocol.enabled=true
nacos.plugin.ai-resource-import.mcp-registry-protocol.endpoint=https://registry.example.com/v0/servers

Enable a Skill well-known registry:

nacos.plugin.ai-resource-import.skills-well-known.enabled=true
nacos.plugin.ai-resource-import.skills-well-known.endpoint=https://skills.example.com

skills-well-known supports discovery schema v0.1.0 and v0.2.0. For a registry root, it tries /.well-known/agent-skills/index.json and then /.well-known/skills/index.json.

Configuration definitions

Canonical full keys use:

nacos.plugin.ai-resource-import.{pluginName}.{itemKey}

Common items:

All current definitions are required=false and sensitive=false. mcp-official and skills-sh expose only the four RUNTIME display/limit fields. The two configurable endpoint implementations expose all seven.

Runtime PUT cannot add, change, or remove endpoint, allow-http, or allow-private-network. Change static configuration and restart. The other four fields are runtime-effective, and a new immutable Builder snapshot is used by subsequent requests.

Effective config and aliases

Effective values use:

LOCAL_ONLY > RUNTIME_PERSISTED > STATIC > DEFAULT

Old nacos.plugin.ai.importer.* keys remain aliases for one migration window:

Fixed-source endpoint overrides, auth-ref, source/global timeouts, max-page-count, block-private-network, global defaults, and arbitrary properties.* are removed.

Flow and lifecycle

list sources -> search -> explicit user selection -> validate -> execute

• Search builds one service and returns only candidate summaries, not MCP tools, Skill packages, or secrets.
• Validate and execute each build one service, reuse it for all selected items in that operation, and close it in finally.
• Fetch returns an artifact but never writes Nacos directly. A resource Operator validates and persists it.
• The browser must not select search results by default. Select-all must still allow individual deselection.

Unified APIs:

Security boundary

• Requests cannot submit arbitrary URLs, IPs, registry roots, or credentials.
• HTTPS is required by default, and loopback, link-local, multicast, and private DNS results are blocked.
• Only operator-owned configurable sources can opt in to allow-http or allow-private-network.
• Derived URLs and redirects must reapply the same network policy.
• HTTP responses and artifacts are capped by max-artifact-size; result/file counts are capped by max-item-count.
• Skill import must not execute scripts and must validate paths, digests, and aggregate archive size.

Develop a source

Implement com.alibaba.nacos.plugin.ai.importer.spi.AiResourceImportServiceBuilder and register it through Java SPI. The Builder itself is the managed plugin and implements PluginConfigSpec:

SPI file:

META-INF/services/com.alibaba.nacos.plugin.ai.importer.spi.AiResourceImportServiceBuilder

Duplicate names use first-wins with a WARN.

Breaking change and migration

The old Importer/Source dual SPI is removed with no compatibility adapter. External plugins must be migrated and recompiled:

• Remove AiResourceImportSource and the Source Provider SPI.
• Remove nacos.ai.resource.import.sources[N].*, presets, and cloned endpoints.
• Make the Builder pluginName() the fixed source ID, implement PluginConfigSpec, and use no-argument build().
• Move effective properties to canonical full keys.

Old MCP import compatibility APIs are disabled by default. A temporary migration can set nacos.ai.resource.import.legacy-mcp-api-enabled=true. Fetching a user URL also requires the explicit nacos.ai.resource.import.allow-user-url=true opt-in and is not a long-term solution.

See Plugin Migration Guide and Compatibility and Deprecation.