# n8n Local Control

[![Agent Plugins 1.0](https://img.shields.io/badge/Agent%20Plugins-1.0-111111)](https://agent-plugins.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Turn natural-language requests into configured n8n workflows and safely operate a local n8n Docker stack from compatible AI agents.

This repository is dual packaged:

- `plugin.json` and `mcp.json` implement the portable [Agent Plugins 1.0](https://agent-plugins.org/specification) format.
- `.codex-plugin/plugin.json` and `.mcp.json` retain native Codex packaging.
- `skills/` contains portable [Agent Skills](https://agentskills.io/specification).

## Capabilities

- Search n8n nodes and templates, construct workflows, validate nodes and complete workflows, inspect executions, and manage credentials through pinned `n8n-mcp@2.68.0`.
- Discover and call the live n8n Public API with exact OpenAPI allowlisting.
- Use expiring two-phase confirmation tokens for API writes and stack mutations.
- Inspect health and logs; start, stop, restart, back up, restore, and upgrade the exact Docker Compose deployment discovered from container labels.
- Create consistent stopped-volume backups with SHA-256 metadata and restore/upgrade rollback.

## Requirements

- Node.js 18 or newer.
- n8n available at `http://localhost:5678` by default.
- For full Windows stack control: PowerShell and Docker Desktop with an n8n Compose deployment.
- An n8n API key is optional for documentation and static validation, but required for workflow/API management.

## Agent Plugins installation

Clone the repository and load its directory with an Agent Plugins 1.0-compatible client. The portable MCP entries use `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` exactly as defined by the specification.

```powershell
git clone https://github.com/RobertIonutF/n8n-local-control.git
```

The package is Windows-first for DPAPI and Docker administration. On other platforms the portable skills and MCP workflow engine can still load, but API-key storage must be supplied by the client or process environment and Windows stack tools are unavailable.

## One-time Windows setup

1. In n8n, open **Settings -> n8n API** and create an API key with only the scopes you want the agent to use.
2. Run:

   ```powershell
   & '.\scripts\setup.ps1'
   ```

3. Paste the key into the hidden terminal prompt. The script validates it and stores only a Windows DPAPI-encrypted value.

The setup script discovers the compose project, service, compose file, and n8n data volume from Docker labels. Override discovery only when needed:

```powershell
& '.\scripts\setup.ps1' -Container n8n -BaseUrl 'http://localhost:5678' -ComposeFile 'D:\path\to\docker-compose.yml'
```

When an Agent Plugins client supplies `PLUGIN_DATA`, run setup from a terminal with that environment value or pass `-StateDirectory` explicitly so the launcher and setup helper share the same state directory. Codex falls back to `%LOCALAPPDATA%\Codex\n8n-local-control`.

Never paste the n8n API key or third-party credential secrets into chat.

## Safety model

Read-only inspection, workflow design, inactive creation, and static validation can run autonomously. Activation, publication, side-effectful execution, deletion, credential changes, users/security, community packages, service interruption, restore, and upgrade require explicit confirmation. The local MCP server also requires an expiring prepared-operation token before mutations.

## Validation

```powershell
python .\scripts\validate_agent_plugin.py
node .\tests\server.test.mjs
node .\tests\mcp-handshake.test.mjs
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\dpapi.test.ps1
```

Codex plugin authors can additionally run the `plugin-creator` validator from their local Codex installation.

Live Docker tests are intentionally separate because they briefly stop n8n or create disposable Docker resources.

## Privacy

The plugin does not embed credentials. The upstream n8n-MCP telemetry is disabled by the launcher. Sensitive API response fields are redacted, and Docker/API targets are restricted before execution.

## License

MIT. See [LICENSE](LICENSE).