Nacos Plugin

Author: aias00
Version: 1.0.0
Type: tool
Minimum Dify Version: 1.5.1

Overview

This plugin provides ten Dify tools for working with Nacos Config:

• nacos_reader: read configuration content
• nacos_writer: write or update configuration content
• nacos_delete: delete a configuration item
• nacos_list: list configuration items in one namespace
• nacos_history: list historical versions for one configuration item
• nacos_history_detail: inspect one historical version
• nacos_history_rollback: roll back to one historical version
• nacos_namespace_list: list namespaces
• nacos_namespace_manage: get, check, create, update, or delete one namespace
• nacos_listener_query: query current listeners by config or by client IP

The plugin is focused on Nacos Config. It does not manage service discovery, instance registration, or other naming features.

Authentication and connection settings are configured once at the provider level. Individual tool calls only need business parameters such as namespace, data_id, group, and pagination.

Compatibility

This plugin supports both Nacos 2.x and Nacos 3.x.

Config CRUD and history

For config read, write, delete, history list, history detail, and rollback:

• it first tries the classic 2.x HTTP APIs when they exist
• if Nacos returns 410 Gone, it automatically falls back to the 3.x APIs

Main endpoints used:

• 2.x
  • /nacos/v2/cs/config
  • /nacos/v2/cs/history/configs
  • /nacos/v2/cs/history/list
  • /nacos/v2/cs/history
• 3.x
  • /nacos/v3/client/cs/config
  • /nacos/v3/admin/cs/config
  • /nacos/v3/admin/cs/history/configs
  • /nacos/v3/admin/cs/history/list
  • /nacos/v3/admin/cs/history

Namespace management

Namespace list and namespace management support both 2.x and 3.x namespace APIs.

Main endpoints used:

• 2.x
  • /nacos/v2/console/namespace/list
  • /nacos/v2/console/namespace
• 3.x
  • /nacos/v3/admin/core/namespace/list
  • /nacos/v3/admin/core/namespace

Listener query

Listener query uses the 3.x admin listener APIs:

• /nacos/v3/admin/cs/config/listener
• /nacos/v3/admin/cs/listener

This means nacos_listener_query requires Nacos 3.x.

Nacos 3.x auth behavior

There are two common Nacos 3.x deployment styles:

1. relaxed or compatible auth
   The plugin can often work with just username and password.

2. strict 3.x auth
   Some deployments also require an identity header. In that case you must provide:

   • identity_key
   • identity_value

For strict 3.x environments, these values are deployment-specific. A common example is:

• identity_key=serverIdentity
• identity_value=<your-identity-value>

Provider Credentials

Configure these once when installing or debugging the plugin:

Credential	Type	Required	Description
server_addresses	text-input	Yes	Nacos server address, for example localhost:8848 or https://nacos.example.com:8848
username	text-input	Yes	Nacos username
password	secret-input	Yes	Nacos password
identity_key	text-input	No	Optional Nacos 3.x identity header key, for example serverIdentity
identity_value	secret-input	No	Optional Nacos 3.x identity header value for strict auth environments

Illustrative provider credential setup (using placeholder values):

Local networking note

The correct Nacos address depends on how the plugin is running:

• Remote debug runtime on the host: use a host-reachable address such as 127.0.0.1:8848 or your-host:8848
• Package-installed provider inside Dify Docker networking: use a container-reachable address such as nacos:8848 or another Docker-network hostname

The second form is required because the installed plugin runs inside Docker-managed runtime containers and does not see the host's localhost.

Tool Summary

nacos_reader

Returns:

{
  "success": true,
  "config": "..."
}

nacos_writer

Returns:

{
  "success": true,
  "result": true
}

nacos_delete

Returns:

{
  "success": true,
  "result": true
}

nacos_list

Returns namespace-scoped config list data:

{
  "success": true,
  "configs": [],
  "total_count": 0,
  "page_number": 1,
  "pages_available": 1
}

nacos_history

Returns paginated history data:

{
  "success": true,
  "history": {
    "total_count": 1,
    "page_number": 1,
    "pages_available": 1,
    "page_items": []
  }
}

nacos_history_detail

Returns one historical version object:

{
  "success": true,
  "history_version": {
    "id": "7",
    "dataId": "app.yaml",
    "groupName": "DEFAULT_GROUP",
    "content": "..."
  }
}

nacos_history_rollback

This tool implements rollback by:

1. fetching one historical version
2. extracting its content
3. re-publishing that content to the target config

Returns:

{
  "success": true,
  "result": true,
  "history_version": {
    "id": "7",
    "content": "..."
  }
}

nacos_namespace_list

Returns:

{
  "success": true,
  "namespaces": [],
  "total_count": 0
}

nacos_namespace_manage

Supported action values:

• get
• check
• create
• update
• delete

Typical outputs:

{
  "success": true,
  "action": "get",
  "namespace": {
    "namespace": "public",
    "namespaceShowName": "public"
  }
}

{
  "success": true,
  "action": "check",
  "exists": true
}

{
  "success": true,
  "action": "create",
  "result": true
}

nacos_listener_query

Supported query_type values:

• config: query listeners for one config item
• ip: query subscriptions for one client IP

Returns:

{
  "success": true,
  "query_type": "config",
  "listeners_status": {},
  "entry_count": 0
}

Parameter Notes

Default namespace in config tools

For config-domain tools such as:

• nacos_reader
• nacos_writer
• nacos_delete
• nacos_list
• nacos_history
• nacos_history_detail
• nacos_history_rollback
• nacos_listener_query with query_type=config

the following inputs all target the default namespace:

• omit namespace
• namespace=""
• namespace="public"

Internally these are normalized to "".

Default namespace in namespace management

For nacos_namespace_manage, the namespace_id parameter is normalized a little differently:

• omit namespace_id
• namespace_id=""
• namespace_id="public"

These all target the default namespace, but namespace-management APIs conceptually operate on the namespace identity itself, so the tool treats them as the default namespace target rather than a config-path empty namespace value.

Shared config parameters

Parameter	Type	Required	Description
namespace	string	No	Optional namespace ID for config-domain tools
data_id	string	Depends on tool	Config dataId
group	string	Depends on tool	Config group, usually DEFAULT_GROUP

Pagination

Used by:

• nacos_list
• nacos_history

Parameters:

Parameter	Type	Required	Description
page_no	string	No	Page number, default 1
page_size	string	No	Page size, default 100

History detail and rollback

Used by:

• nacos_history_detail
• nacos_history_rollback

Parameters:

Parameter	Type	Required	Description
history_id	string	Yes	Historical version ID returned by nacos_history

Namespace management

Used by:

• nacos_namespace_manage

Parameters:

Parameter	Type	Required	Description
action	string	Yes	One of get, check, create, update, delete
namespace_id	string	Depends on action	Target namespace ID; optional custom ID for create
namespace_name	string	Required for create and update	Namespace display name
namespace_desc	string	No	Namespace description

Listener query

Used by:

• nacos_listener_query

Parameters:

Parameter	Type	Required	Description
query_type	string	Yes	config or ip
aggregation	string	No	Boolean-like string, default true
namespace	string	No	Used when query_type=config
data_id	string	Required for query_type=config	Target config dataId
group	string	Required for query_type=config	Target config group
client_ip	string	Required for query_type=ip	Client IP to inspect

Validation Workflows

The source repository includes two reusable validation workflow DSL files:

• nacos-full-validation-workflow.yml
• nacos-management-validation-workflow.yml

Both workflow artifacts are wired to the package-installed provider:

• aias00/nacos/nacos

These workflow DSL files are repository assets for validation and documentation. They are intentionally excluded from the packaged plugin artifact.

If you only have a remote-debug provider, replace the provider_id and provider_name values in the DSL before importing.

nacos-full-validation-workflow.yml

This workflow validates the config CRUD lifecycle:

• nacos_writer
• delay for read-after-write consistency
• nacos_reader
• nacos_list
• nacos_history
• nacos_delete

nacos-management-validation-workflow.yml

This workflow validates the expanded config-management surface:

• nacos_namespace_manage with create
• nacos_namespace_manage with update
• nacos_namespace_manage with get
• nacos_namespace_manage with check
• nacos_namespace_list
• nacos_writer twice
• nacos_history
• code node to select a rollback history version ID
• nacos_history_detail
• nacos_history_rollback
• nacos_reader after rollback
• nacos_listener_query by config
• nacos_listener_query by IP
• nacos_delete
• nacos_namespace_manage with delete
• nacos_namespace_manage with final check

The current validated local run produced:

• namespace_create_result = true
• namespace_update_result = true
• history_count = 2
• rollback_result = true
• config_after_rollback = version: 1 ...
• listener_config_entries = 0
• listener_ip_entries = 0
• delete_config_result = true
• namespace_delete_result = true
• namespace_exists_after_delete = false

The current management screenshots were refreshed using a more visible custom input set:

• namespace_id = showcase-namespace-20260427
• data_id = showcase-config-20260427.yaml
• group = SHOWCASE_GROUP

Management workflow successful run summary:

Management workflow detail tab:

Management workflow trace tab:

Operational Notes

Read-after-write note

In the local official Nacos 3.1.1 validation environment, there can be a short read-after-write inconsistency window:

• write succeeds
• immediate read can temporarily return null
• a short delay makes the read stable again

That is why the bundled validation workflow inserts a short delay before nacos_reader.

List semantics

nacos_list.total_count is namespace-scoped, not "how many items match the current data_id".

Use:

• nacos_reader
• nacos_history
• nacos_history_detail

for per-config assertions.

Listener query semantics

nacos_listener_query is a finite query tool, not a long-lived streaming subscription. That is intentional for Dify tool execution:

• query_type=config tells you which clients are currently listening to one config item
• query_type=ip tells you which config items one client IP is currently subscribed to

Example Provider Configuration

Use values that match your own environment. For example:

• server_addresses=your-nacos-host:8848
• username=your-username
• password=your-password
• identity_key=serverIdentity
• identity_value=your-identity-value

Known Limits

• The plugin still focuses on Config, not Naming/Discovery.
• nacos_listener_query depends on Nacos 3.x admin listener APIs.
• Rollback is implemented by re-publishing historical content, not by a dedicated server-side rollback transaction.