Content
# n8n Agent Tools
Ferramenta global instalável para agentes de IA trabalharem com projetos n8n versionáveis sem copiar `tools/` para cada repo.
O objetivo é simples: cada projeto n8n vira um repositório Git próprio, com workflows em JSON, contexto local, MCP configurado e credenciais fora do repositório. A CLI global `n8n-agent` é instalada uma vez e usada por Codex, Claude, Gemini, Copilot e IDEs com agentes.
## O Que Este Repo Entrega
- CLI global: `n8n-agent`.
- Servidor MCP: `n8n-agent mcp`.
- Bootstrap de projeto: `n8n-agent project init`.
- Leitura e edição local de workflows JSON.
- Sync explícito com a API pública do n8n.
- Escopo cloud por projeto para evitar varrer a instância inteira.
- Profiles e credenciais locais fora do repo.
- Modo `local-only` para bloquear cloud.
- Biblioteca TOON de exemplos de nodes reais.
- Plugin inicial para agentes em `plugins/n8n-agent-mcp`.
- Projeto real de referência preservado em `examples/cs-pipeline`.
## Modelo Mental
O projeto consumidor é a fonte local de trabalho. A nuvem n8n é consultada ou alterada só quando o usuário pedir.
```text
repo do projeto n8n
n8n-agent.json
.mcp.json
context/
scripts/
.n8n-agent/cloud-scope.json
n8n-workflows/
máquina do usuário
~/.config/n8n-agent/credentials.json
n8n-agent instalado globalmente
```
Segredos nunca devem entrar no repo. A API pública do n8n também não expõe as pastas da UI, então o escopo remoto precisa ser declarado por tags, regex de nome e manifesto de IDs.
## Instalação
Durante desenvolvimento neste checkout:
```bash
uv run --project . n8n-agent --help
uv run --project . n8n-agent mcp
```
Depois de publicar o repositório:
```bash
uv tool install git+https://github.com/SoTahTech-Solucoes-Tecnologicas-LTDA/n8n-agent-mcp.git
n8n-agent --help
```
## Criar Um Projeto n8n
```bash
mkdir meu-projeto-n8n
cd meu-projeto-n8n
n8n-agent project init \
--name "meu-projeto-n8n" \
--workflows-dir n8n-workflows \
--profile prod \
--host https://n8n.example.com \
--with-readme \
--with-mcp \
--with-context
```
O comando cria:
```text
n8n-agent.json
.mcp.json
.gitignore
README.md
context/n8n-agent/*.md
scripts/README.md
.n8n-agent/cloud-scope.json
n8n-workflows/
```
Ele não inicializa Git. Revise os arquivos e rode `git init` manualmente quando quiser.
## Credenciais e Profiles
Salve credenciais fora do repositório:
```bash
printf "$N8N_API_KEY" | n8n-agent project credentials set \
--profile prod \
--host https://n8n.sotahtech.com/ \
--api-key-stdin
```
Verifique status sem revelar valores:
```bash
n8n-agent project credentials list
n8n-agent project config show --with-secrets-status
```
Teste credencial explicitamente:
```bash
n8n-agent project credentials test --profile prod
```
Profiles versionáveis ficam em `n8n-agent.json`; segredos ficam em `~/.config/n8n-agent/credentials.json`.
Para alternar profile ativo:
```bash
n8n-agent project profile list
n8n-agent project profile set-active staging --host https://staging-n8n.example.com
```
`N8N_AGENT_PROFILE` funciona como override para o processo atual:
```bash
N8N_AGENT_PROFILE=staging n8n-agent cloud status --scope
```
Para reutilizar a mesma instância em vários projetos, use uma instância global local:
```bash
printf "$N8N_API_KEY" | n8n-agent project credentials set \
--profile prod \
--instance acme-prod \
--host https://n8n.acme.example \
--api-key-stdin
n8n-agent project credentials set --profile prod --credential-ref acme-prod
```
## Escopo Cloud
Sem escopo, uma instância n8n pode ter workflows de várias empresas e projetos. Use escopo antes de listar, puxar ou comparar em massa.
```bash
n8n-agent project scope init --tag "Projeto X"
n8n-agent project scope show
```
Arquivo versionável:
```json
{
"version": 1,
"mode": "manifest",
"tags": ["Projeto X"],
"nameRegex": "^\\[Projeto X\\]",
"workflowIds": [],
"includeInactive": true
}
```
Comandos que aceitam `--scope`:
```bash
n8n-agent cloud list --scope --profile prod
n8n-agent cloud status --scope --profile prod
n8n-agent cloud diff --scope --profile prod
n8n-agent cloud pull --scope --profile prod
```
Para manter um manifesto explícito:
```bash
n8n-agent project scope add --workflow-id abc123
n8n-agent project scope remove --workflow-id abc123
```
Sem `--scope`, a saída deixa claro que está consultando `all_remote`.
## Fluxo Recomendado
1. Instale `n8n-agent` globalmente.
2. Crie um repo Git do projeto n8n.
3. Rode `n8n-agent project init`.
4. Configure credencial por profile.
5. Defina o escopo cloud por tag, regex ou IDs.
6. Faça o pull inicial só do escopo.
7. Gere exemplos TOON.
8. Abra a IDE com MCP.
9. Trabalhe local-first.
10. Faça push explícito só quando pedir.
Comandos:
```bash
n8n-agent cloud list --scope --profile prod
n8n-agent cloud pull --scope --profile prod
n8n-agent local list
n8n-agent examples ingest --all
n8n-agent local validate --all
```
## Trabalho Local
Ferramentas locais:
```bash
n8n-agent local list
n8n-agent local index <workflow>
n8n-agent local get-node <workflow> --name "Node"
n8n-agent local get-connections <workflow>
n8n-agent local search --type httpRequest
n8n-agent local edit-node <workflow> --name "Node" --set parameters.foo=bar
n8n-agent local validate <workflow>
```
Edições são pensadas para agentes: primeiro dry-run, depois `--apply`, e validação ao final.
## Modo Local-only
Quando o usuário pedir para trabalhar apenas no estado local:
```bash
n8n-agent project mode local-only --reason "trabalho local divergente do remoto"
```
Enquanto ativo, comandos cloud falham antes de procurar credencial ou chamar API.
Para liberar:
```bash
n8n-agent project mode cloud-ok
```
No MCP, agentes devem preferir `project_mode_set scope=session mode=local-only` para bloquear só o chat atual.
## MCP e IDEs
Comando do servidor:
```bash
n8n-agent mcp
```
Config genérica:
```json
{
"mcpServers": {
"n8n-agent": {
"command": "n8n-agent",
"args": ["mcp"],
"env": {
"N8N_AGENT_ROOT": "."
}
}
}
}
```
Neste repo de desenvolvimento, `.mcp.json` usa `uv run --project . n8n-agent mcp`. Em projetos consumidores, prefira `n8n-agent mcp`.
## Biblioteca TOON de Exemplos
Gere exemplos sanitizados a partir de workflows reais:
```bash
n8n-agent examples ingest --all
n8n-agent examples search --type httpRequest
n8n-agent examples read <example-id>
```
Os exemplos ficam em `.n8n-agent/examples`. Eles ajudam agentes a criar nodes com parâmetros reais, especialmente community nodes e credenciais específicas.
## Layout Deste Repositório
```text
.
├── pyproject.toml # pacote Python global
├── uv.lock # lock de desenvolvimento
├── README.md # documentação principal
├── docs/ # guias de uso e arquitetura
├── prompts/ # prompt mestre empacotado
├── tools/ # código do pacote
│ ├── n8n_agent/ # dispatcher CLI e templates
│ ├── n8n_project/ # init/config/profile/credentials/scope/mode/context
│ ├── n8n_local/ # leitura, edição e validação local
│ ├── n8n_cloud/ # API pública n8n
│ ├── n8n_examples/ # biblioteca TOON
│ ├── paths/ # utilitários auxiliares
│ └── common/ # infra compartilhada
├── tests/ # testes de fumaça e contratos principais
├── plugins/n8n-agent-mcp/ # plugin inicial para agentes
├── examples/cs-pipeline/ # projeto real preservado como referência
└── .github/workflows/ci.yml # CI
```
Material externo de referência e docs antigas foram removidos da árvore principal para manter o futuro repositório enxuto. O exemplo real `examples/cs-pipeline` foi preservado.
## Documentação
- [Quickstart](docs/QUICKSTART.md)
- [Criando um projeto n8n versionável](docs/CRIANDO_PROJETO_VERSIONAVEL.md)
- [Múltiplas instâncias e empresas](docs/MULTIPLAS_INSTANCIAS.md)
- [Agentes e IDEs](docs/AGENTES_E_IDES.md)
- [Guia de ferramentas MCP](docs/GUIA_FERRAMENTAS.md)
- [Local-only mode](docs/LOCAL_ONLY.md)
- [Cloud scope, tags e pathRules](docs/CLOUD_SCOPE.md)
- [Biblioteca TOON de exemplos](docs/EXEMPLOS_TOON.md)
- [Pull/push com segurança](docs/PUBLISH_PULL_PUSH_SEGURO.md)
- [Layout do repositório](docs/REPOSITORY_LAYOUT.md)
## Desenvolvimento
Validações principais:
```bash
python3 -m compileall -q tools prompts tests
uv run --project . --group dev pytest -q
uv build --sdist --wheel
```
CI roda compile, testes e build.
Antes de criar o repositório Git, confira que artefatos locais não existem:
```bash
find . -maxdepth 3 \( -name '.venv' -o -name '__pycache__' -o -name 'dist' -o -name 'build' -o -name '*.egg-info' -o -name '.pytest_cache' \) -print
```
## O Que Fica Fora Do Repo
Ignorado por padrão:
- `.env`, `tools/.env`, `*.local.json`
- `~/.config/n8n-agent/credentials.json`
- `.n8n-agent/state/`
- `.n8n-agent/tmp/`
- `.n8n-agent/mode.json`
- `.venv/`, `dist/`, `build/`, `*.egg-info/`, caches
- `.claude/`, `.idea/`, `.vscode/`
Arquivos legados sensíveis de projetos n8n, como `env.json` e `n8nac-config.json`, também ficam ignorados.
