@acropole/skills 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +4 -3
  2. package/package.json +4 -4
  3. package/skills/acropole/SKILL.md +2 -0
  4. package/skills/acropole/references/arquitetura.md +29 -5
  5. package/skills/acropole/references/fluxos/app-novo.md +4 -4
  6. package/skills/acropole/references/fluxos/tela-nova.md +1 -1
  7. package/skills/apollo/references/subscriptions.md +10 -4
  8. package/skills/apollo/references/testes-build.md +1 -0
  9. package/skills/auto-servico/SKILL.md +153 -0
  10. package/skills/auto-servico/references/diagnostico.md +42 -0
  11. package/skills/auto-servico/references/roteiros.md +63 -0
  12. package/skills/auto-servico/references/tools.md +108 -0
  13. package/skills/docker/SKILL.md +3 -0
  14. package/skills/docker/references/podman-local.md +73 -0
  15. package/skills/express/references/dados.md +3 -1
  16. package/skills/fastapi/SKILL.md +4 -4
  17. package/skills/fastapi/references/banco.md +53 -50
  18. package/skills/fastapi/references/estrutura.md +2 -2
  19. package/skills/fastapi/references/integracoes.md +8 -0
  20. package/skills/hefesto/SKILL.md +49 -14
  21. package/skills/hefesto/references/diagnostico.md +15 -5
  22. package/skills/hefesto/references/fluxo.md +64 -35
  23. package/skills/hefesto/references/mcp-diagnostico.md +44 -0
  24. package/skills/hefesto/references/mcp-roteiros.md +53 -0
  25. package/skills/hefesto/references/mcp-tools.md +94 -0
  26. package/skills/orfeu/SKILL.md +1 -1
  27. package/skills/orfeu/references/diferencas.md +1 -1
  28. package/skills/orfeu/references/node.md +1 -1
  29. package/skills/orquestracao/SKILL.md +1 -1
  30. package/skills/orquestracao/templates/spec.md +1 -1
  31. package/skills/trismegisto/SKILL.md +4 -4
  32. package/skills/trismegisto/references/angular-api.md +653 -507
  33. package/skills/trismegisto/references/angular-exports.md +541 -130
  34. package/skills/trismegisto/references/angular-types.md +1 -1
  35. package/skills/trismegisto/references/angular.md +28 -8
  36. package/skills/trismegisto/references/catalogo/icones.json +5 -0
  37. package/skills/trismegisto/references/catalogo/seletores.json +452 -31
  38. package/skills/trismegisto/references/catalogo/tokens.json +136 -16
  39. package/skills/trismegisto/references/spine-api.md +181 -44
  40. package/skills/trismegisto/references/spine-recipes.md +1 -1
  41. package/skills/trismegisto/references/spine.md +4 -3
package/README.md CHANGED
@@ -21,8 +21,9 @@ Cada skill cobre uma parte da stack e elas se complementam (a `orquestracao` enc
21
21
  | `express` | Servidores Node com Express: middlewares, rotas REST, erros, Knex, shutdown | "cria a rota REST de upload no servidor Node" |
22
22
  | `fastapi` | Serviços Python com FastAPI: domínios, settings, SQLAlchemy, envelope, pytest | "adiciona o domínio de faturas no serviço Python" |
23
23
  | `docker` | Dockerfile e `.dockerignore` (Angular estático, Node, Python): multi-stage, CMD exec, não-root, healthcheck | "escreve o Dockerfile desse serviço", "o container demora a parar" |
24
- | `hefesto` | Deploy pela plataforma Hefesto: aplicação, ambientes, variáveis, deploy/redeploy, rollback, diagnóstico | "prepara esse app para subir no Hefesto", "o deploy falhou" |
24
+ | `hefesto` | Deploy pela plataforma Hefesto: aplicação, ambientes, variáveis, deploy/redeploy, rollback, diagnóstico, e o MCP de deploy (hefesto-mcp) para um agente de IA | "prepara esse app para subir no Hefesto", "o deploy falhou", "faz o redeploy do pedidos-api em homol pelo MCP" |
25
25
  | `orquestracao` | Mudança grande do pedido à entrega (spec → plano em itens Txx → execução por vários agentes/sessões com reserva atômica via `coord.sh` → provas → Argos → fechamento) e como paralelizar com subagentes | "faz a spec e o plano", "paraleliza entre agentes", "distribui esses itens" |
26
+ | `auto-servico` | MCP do auto-serviço do Argos (argos-mcp): configurar um agente de IA (uma conexão por aplicação, `x-app-token`, escopos), roteiros das tools (tela, acesso, permissões) e diagnóstico | "configura o agente para usar o MCP do Argos", "publica a tela pelo MCP" |
26
27
  | `documentacao` | Manual das telas Angular: `README.md`/`ESPECIFICACAO.md` ligados no `document` da rota, loader `.md`, revisão da doc a cada mudança da tela (registro de revisão em `.documentacao.json`) | "documenta a tela de pedidos", "a doc dessa tela ainda vale?" |
27
28
 
28
29
  ## Subagentes revisores
@@ -127,7 +128,7 @@ fonte do Trismegisto) copia para `skills/<skill>/scripts/nucleo.mjs`. Fixtures d
127
128
 
128
129
  ### Build e release
129
130
 
130
- No disco, este repo fica em `astra/packages/acropole` (`github.com/xlucvvs/acropole`, branch `master`).
131
+ No disco, este repo fica em `astra/packages/acropole` (`github.com/konvndor/acropole`, branch `master`).
131
132
 
132
133
  ```bash
133
134
  scripts/build-publish.sh build # npm test + npm pack -> tarballs/acropole-skills-<versão>.tgz (fora do git)
@@ -149,7 +150,7 @@ Trusted Publishing (OIDC, sem `NPM_TOKEN` no repositório), e ninguém cria tag
149
150
 
150
151
  **Environment `release`.** O job de publicação usa o environment `release`, criado no GitHub **sem regras de
151
152
  proteção** (repo privado em conta Free, sem *Required reviewers*). Ele existe porque é o nome cadastrado no
152
- Trusted Publisher do npm (dono `xlucvvs`, repositório `acropole`, workflow `release.yml`, environment `release`):
153
+ Trusted Publisher do npm (dono `konvndor`, repositório `acropole`, workflow `release.yml`, environment `release`):
153
154
  o npm só aceita o token OIDC vindo dele. A aprovação é o clique em *Run workflow*.
154
155
 
155
156
  **Primeira publicação (1.0.0).** O Trusted Publisher só pode ser usado depois que o pacote existe no npm, então a
package/package.json CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "name": "@acropole/skills",
3
- "version": "1.2.0",
4
- "description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto e documentação das telas. Instale com: npx @acropole/skills",
3
+ "version": "1.4.0",
4
+ "description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto, documentação das telas e os MCPs do auto-serviço do Argos e de deploy do Hefesto. Instale com: npx @acropole/skills",
5
5
  "bin": { "acropole-skills": "bin/install.js" },
6
6
  "files": ["bin", "skills", "agents"],
7
7
  "engines": { "node": ">=18" },
8
8
  "license": "MIT",
9
- "repository": { "type": "git", "url": "git+https://github.com/xlucvvs/acropole.git" },
10
- "keywords": ["claude", "claude-code", "skill", "skills", "angular", "apollo", "graphql", "express", "fastapi", "trismegisto", "orfeu", "docker", "hefesto", "deploy", "documentacao", "documentation", "markdown", "agents", "code-review"],
9
+ "repository": { "type": "git", "url": "git+https://github.com/konvndor/acropole.git" },
10
+ "keywords": ["claude", "claude-code", "skill", "skills", "angular", "apollo", "graphql", "express", "fastapi", "trismegisto", "orfeu", "docker", "hefesto", "deploy", "documentacao", "documentation", "markdown", "agents", "code-review", "mcp", "argos"],
11
11
  "scripts": {
12
12
  "bump": "node scripts/bump.mjs",
13
13
  "sync": "node scripts/sync-generated.mjs",
@@ -59,6 +59,8 @@ acima e pergunte.
59
59
  | auditoria, operação, `PUBLIC`, `traceparent`, chamada entre serviços | orfeu (+ a skill do serviço) |
60
60
  | Dockerfile, imagem, container, `.dockerignore` | docker (+ express/fastapi/angular para a parte de deploy da stack) |
61
61
  | deploy, publicar o serviço, Hefesto, ambiente | hefesto → docker |
62
+ | agente de IA no Argos, MCP do auto-serviço, `.mcp.json`/`x-app-token` para um agente, "publica a tela/dá acesso pelo MCP" | auto-servico |
63
+ | agente de IA no Hefesto, MCP de deploy, "faz o deploy/redeploy pelo MCP", "por que o deploy falhou" com as tools do hefesto-mcp | hefesto |
62
64
  | "revisa", "confere", antes de abrir PR | este fluxo `revisar` |
63
65
  | versões desalinhadas, "não sobe", configuração estranha | este fluxo `doctor` |
64
66
 
@@ -11,7 +11,7 @@ decisões que valem para todas as camadas. Divergiu de um app para outro? Este a
11
11
  ├── angular/ front: Angular 22 + @trismegisto/* + @orfeu/angular
12
12
  ├── graphql/ gateway: Apollo Server sobre Express + @orfeu/node — só repassa para o server
13
13
  ├── server/ API e regra de negócio: FastAPI + orfeu[fastapi] + SQLAlchemy
14
- ├── database/ schema, seed e migrations do Postgres (estrutura idêntica entre os apps)
14
+ ├── database/ migrations do Postgres com Alembic + seed de ambiente (estrutura idêntica entre os apps)
15
15
  ├── compose/ (opcional) docker-compose da stack num host
16
16
  └── README.md componentes, portas, como rodar, padrões seguidos e pendências
17
17
  ```
@@ -41,13 +41,21 @@ navegador ──> angular (estático) ──GraphQL HTTP/WS──> graphql ─
41
41
 
42
42
  ## 3. Caminhos, proxy e portas
43
43
 
44
+ **Regra: toda aplicação vive dentro do próprio contexto.** Tudo do app `<app>` fica sob `/<app>` (o Hefesto sob
45
+ `/hefesto`, o Argos sob `/argos`), em todo ambiente, inclusive no compose local.
46
+
44
47
  | Camada | Caminho público | Prefixo no código |
45
48
  | --- | --- | --- |
46
49
  | angular | `/<app>/` | `baseHref` das configurações de build |
47
50
  | graphql | `/<app>/graphql` (HTTP **e** WebSocket) | `GRAPHQL_PATH` |
48
51
  | server | `/<app>/server` | `api_prefix` (rotas, `/health` e documentação) |
52
+ | mcp | `/<app>/mcp` | `API_PREFIX` |
49
53
 
50
54
  - O proxy encaminha o caminho **completo** (sem strip): cada serviço responde sob o próprio prefixo.
55
+ - O padrão do código (ex.: `api_prefix = "/api"`) **não é contexto**: é só um valor para rodar isolado. Compose,
56
+ `.env.<ambiente>` e deploy definem o prefixo do app (`API_PREFIX: /<app>/server`), e as URLs internas entre
57
+ serviços usam o mesmo caminho (`http://<app>-server:8010/<app>/server`). Nunca "conserte" uma URL quebrada
58
+ trocando o contexto por `/api`; antes de mudar um caminho, veja o padrão do repo (README, testes, config do MCP).
51
59
  - Atrás do proxy, o front deriva callback, logoff, authority e URLs ainda `CHANGE_ME` da própria origem
52
60
  (`applyRuntimeEnvironment`); URL explícita no environment sempre ganha.
53
61
  - Cada app tem **uma porta fixa e única por camada** no desenvolvimento local, registrada no README da raiz,
@@ -63,7 +71,21 @@ chaves de outro (cache, dedup de eventos, `FLUSHDB` de teste):
63
71
  - canais de pub/sub e chaves sempre com o prefixo do app (`<app>:…`) — pub/sub ignora o índice (`PUBLISH` vale
64
72
  para o servidor inteiro), então o prefixo é o que isola as subscriptions;
65
73
  - o índice de cada app por ambiente fica registrado no README da raiz do app; ao criar um app, escolha um índice
66
- livre conferindo os outros apps do mesmo ambiente (`.env.<ambiente>`), não "o próximo número".
74
+ livre conferindo os outros apps do mesmo ambiente (`.env.<ambiente>`), não "o próximo número";
75
+ - **OBRIGATÓRIO: toda conexão ao Redis é nomeada** (`CLIENT SETNAME`). O `maxclients` vale para todos os apps
76
+ juntos, e sem nome o `CLIENT LIST` (campo `name=`) e o redis_exporter não dizem **qual app** abre quantas
77
+ conexões — achar quem estoura o teto vira adivinhação. É só o nome: não é ACL nem usuário por app.
78
+ - Convenção `<app>-<componente>[-<papel>]`, sem espaços (o Redis recusa o `SETNAME` e a conexão não abre):
79
+ `pedidos-server`, `pedidos-graphql-publisher`, `pedidos-graphql-subscriber`, `argos-auth`.
80
+ - Variável `REDIS_CLIENT_NAME` sobrescreve o nome (padrão no código = `<app>-<componente>`); quando há papel,
81
+ ele é sufixado: `${REDIS_CLIENT_NAME}-publisher`. Vazio = padrão; com espaço, a subida falha.
82
+ - **ioredis**: opção `connectionName` em cada `new Redis(...)` — vale também com Sentinel (é a conexão com o
83
+ master); no Cluster, em `redisOptions.connectionName`; conexão extra (`duplicate()`, subscriber) recebe o
84
+ nome do papel (`` client.duplicate({ connectionName: `${base}-subscriber` }) ``).
85
+ - **redis-py**: `client_name=` no `redis.ConnectionPool(...)` — vale para todas as conexões do pool (e para
86
+ o `pubsub()`, que tira a conexão do mesmo pool).
87
+ - Um teste prova o nome padrão e a sobrescrita por `REDIS_CLIENT_NAME`; a variável vai no `.env.example`.
88
+ - **Conexão ao Redis sem nome é defeito de revisão**, igual a um índice repetido.
67
89
 
68
90
  ## 4. Ambientes
69
91
 
@@ -74,7 +96,7 @@ Só **`local`**, **`dev`**, **`homol`** e **`prod`** — em toda camada, com o m
74
96
  | angular | `--configuration <ambiente>` (build/serve) | `src/core/environments/environment.<ambiente>.ts` (versionados, sem segredo); `environment.ts` = `local` |
75
97
  | graphql | `NODE_ENV` (`cross-env` nos scripts) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
76
98
  | server | `APP_ENV` (comando, `poe start:<ambiente>` ou `src/.env`) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
77
- | database | — | `env/.env` (não versionado) + `env/.env.example` |
99
+ | database | `-x env=<ambiente>` / `poe migrate <ambiente>` (padrão `local`) | `env/.env.<ambiente>` (não versionados) + `env/.env.example` |
78
100
 
79
101
  - Em container nenhum arquivo `.env` existe (o `.dockerignore` tira): as variáveis vêm do deploy. Arquivo
80
102
  ausente não pode quebrar a subida.
@@ -139,7 +161,7 @@ do Dockerfile falha com `package.json` e lock divergentes.
139
161
  | angular | `start`, `dev`, `start:local`, `start:homol`, `build` (prod), `build:dev`, `build:homol`, `watch`, `test`, `lint:a11y`, `axe:check`, `codegen` |
140
162
  | graphql | `dev`, `start`, `start:local`, `start:homol`, `build` (typecheck + esbuild), `typecheck`, `start:prod`, `test` |
141
163
  | server | `poe start:local`, `poe start:dev`, `poe start:homol`, `poe test` |
142
- | database | `python build.py [--exec\|--reset\|--seed\|--bootstrap]`, `python -m pytest` |
164
+ | database | `poe migrate <ambiente>`, `poe status <ambiente>`, `poe nova "<descrição>"`, `poe bootstrap <ambiente>`, `poe seed <ambiente>`, `poe seed-regerar <ambiente>`, `poe test` |
143
165
 
144
166
  ## 10. Testes mínimos
145
167
 
@@ -148,7 +170,7 @@ do Dockerfile falha com `package.json` e lock divergentes.
148
170
  | angular | `app.config.spec`, `core.providers.spec`, `environments.spec`, `core.component.spec`, `features.routes.spec` (UUID único, `load()` standalone, documento carregável) + spec de toda tela nova/alterada |
149
171
  | graphql | `builder.test` (subida, path, CORS, introspecção desligada, lote, 400 de sintaxe, 401/403 antes do resolver, encerramento), `builder-falha.test` (Orfeu fora → 503 → 200; campo sem `operation()` não sobe), `builder-padroes.test`, `shutdown.test` (teto → 1), `resolvers.test` (tabela campo → chamada REST) |
150
172
  | server | `test_health`, `test_api_docs` (só `local`; `API_DOCS` força), testes de domínio com SQLite em memória |
151
- | database | suíte compartilhada (estrutura, build, migrations, PGlite) + `test_app.py` |
173
+ | database | suíte compartilhada: migrations do zero, de novo sem efeito, `stamp`, migration nova numerada, confirmação em prod, seed (idempotente, regerar estável) — num Postgres em memória (PGlite por socket) |
152
174
 
153
175
  Validação antes de entregar: suíte e build de cada camada alterada (`ng test` + `ng build`; `vitest` +
154
176
  `typecheck` + `build`; `pytest` em ambiente recriado do zero quando dependência mudou).
@@ -166,6 +188,8 @@ Validação antes de entregar: suíte e build de cada camada alterada (`ng test`
166
188
  - [ ] Pastas `angular/`, `graphql/`, `server/`, `database/` e README da raiz com portas e pendências
167
189
  - [ ] Só `local`/`dev`/`homol`/`prod`; `.env.example` em cada backend; nenhum `.env` versionado
168
190
  - [ ] `REDIS_DB` próprio por ambiente (nenhum outro app no mesmo índice) e prefixo `<app>:` nas chaves/canais
191
+ - [ ] Toda conexão ao Redis nomeada (`<app>-<componente>[-<papel>]`, `REDIS_CLIENT_NAME`; `connectionName` no ioredis, `client_name` no `ConnectionPool` do redis-py), com teste e no `.env.example`
192
+ - [ ] Tudo sob o contexto `/<app>` (front, graphql, server, mcp), também no compose: `API_PREFIX`/`GRAPHQL_PATH` definidos, URLs internas com o prefixo, nada em `/api` genérico
169
193
  - [ ] Gateway sobe negando com `/health` 503 → 200; server com `/health` sob o prefixo
170
194
  - [ ] Encerramento 0/1 com teto de 8 s; `CMD` em forma exec
171
195
  - [ ] Documentação de API só em `local`; TLS desligado avisado; sem `disable_warnings` global
@@ -19,14 +19,14 @@ app de origem — e depois remova o que for específico dele. Copiar do zero de
19
19
  | 1 | **Esqueleto** `angular/`, `graphql/`, `server/`, `database/` + `.gitignore` da raiz, copiados da base sem artefatos nem domínio | acropole | `arquitetura.md` §1 |
20
20
  | 2 | **Front**: nome do projeto no `angular.json` (`outputPath`, `buildTarget`), `baseHref` `/<app>/`, porta nos scripts, `package.json` (nome, versão `0.1.0`), environments dos quatro ambientes com o client/realm do app e o cliente GraphQL `<app>` (`CHANGE_ME` onde a URL deve ser derivada atrás do proxy), `features.routes.ts` vazio com o exemplo comentado, `styles.scss` mínimo, título/`lang="pt-BR"` no `index.html`, `axe-routes.config.json` com a porta e o caminho base. Tire dependências que só a base usava (editor, gráficos) | angular + trismegisto | angular `references/estrutura.md`, `references/testes-build.md` |
21
21
  | 3 | **Specs fixos do front** (`app.config`, `core.providers`, `environments`, `core.component`, `features.routes`) ajustados ao app | angular | angular `references/testes-build.md` |
22
- | 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
22
+ | 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, conexões Redis nomeadas por papel (`<app>-graphql-publisher`/`-subscriber`, `REDIS_CLIENT_NAME`), mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
23
23
  | 5 | **Testes do gateway**: manter os genéricos (subida, autorização com `_noop`, falha de subida, padrões, encerramento), tabela de rotas REST vazia, tirar os de domínio | apollo | apollo `references/testes-build.md` |
24
- | 6 | **Server**: settings só com Argos, Postgres, Redis e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
24
+ | 6 | **Server**: settings só com Argos, Postgres, Redis (com `redis_client_name` = `<app>-server`, `client_name` no `ConnectionPool`) e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
25
25
  | 7 | **Testes do server**: `conftest` com a base do app, `test_health`, `test_api_docs` | fastapi | fastapi `references/testes-deploy.md` |
26
- | 8 | **Banco**: `bootstrap` (role e database `<app>`), `delete/reset.sql`, `create/<app>/01-core.sql` só com `CREATE SCHEMA`, `manifest.yml` com `insert: []`, `env/.env.example`, `test_app.py`, seções "Schemas"/"Particularidades" do `CLAUDE.md` da pasta; `python build.py` para gerar `output/build.sql` | fastapi | fastapi `references/banco.md` |
26
+ | 8 | **Banco**: `database/` copiada da base (Alembic) com o nome do app em `ambiente.py`, `bootstrap.sql` e `env/.env.example`; `0001_linha_de_base` só com o `CREATE SCHEMA`; `seed/` vazio; seções "Schemas"/"Particularidades" do `CLAUDE.md` da pasta; `poe test` | fastapi | fastapi `references/banco.md` |
27
27
  | 9 | **Dockerfiles** das três camadas com as portas novas e o caminho do build do front | docker | docker `references/modelos.md` |
28
28
  | 10 | **README da raiz**: componentes e portas, cadastro no Argos (IDs públicos), como rodar, padrões, pendências | acropole | `arquitetura.md` |
29
- | 11 | **Validação**: instalar e rodar tudo — `ng test` + `ng build` + `lint:a11y`; `vitest` + `typecheck` + `build`; ambiente Python novo + `pytest`; `pytest` do banco (PGlite); importar o `main.py` com variáveis fictícias. Procure no app novo o nome da base (`grep -ri`) e o que sobrar de domínio | acropole | `arquitetura.md` §10 |
29
+ | 11 | **Validação**: instalar e rodar tudo — `ng test` + `ng build` + `lint:a11y`; `vitest` + `typecheck` + `build`; ambiente Python novo + `pytest`; `pytest` do banco (migrations num Postgres em memória); importar o `main.py` com variáveis fictícias. Procure no app novo o nome da base (`grep -ri`) e o que sobrar de domínio | acropole | `arquitetura.md` §10 |
30
30
 
31
31
  Fora do código (diga ao usuário no fim): **redirect URIs** do client no Argos (`<origem>/<app>/callback` e
32
32
  `/logoff`, inclusive `localhost` para o desenvolvimento), **acesso** dos grupos ao client e cada roteador privado
@@ -9,7 +9,7 @@ schema.
9
9
 
10
10
  | # | Passo | Skill | Onde |
11
11
  | --- | --- | --- | --- |
12
- | 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição), **liberá-lo para os grupos** que devem ver a tela (roteador privado sem liberação não aparece no menu) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código | angular | `SKILL.md` "Receita: tela nova", `references/features.md` |
12
+ | 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição), **liberá-lo para os grupos** que devem ver a tela (roteador privado sem liberação não aparece no menu) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código. Exceção: com a conexão MCP do auto-serviço **daquela aplicação** configurada, o agente pode criar rota, router e guard pelas tools, com confirmação do usuário (skill **auto-servico**, roteiro "Publicar uma tela nova") | angular / auto-servico | `SKILL.md` "Receita: tela nova", `references/features.md` |
13
13
  | 2 | **Operação no backend** que a tela vai chamar (Query/Mutation ou rota REST), com operação do Orfeu, `Method` explícito, `Level` e auditoria. Se ainda não existe, rode antes o fluxo [endpoint-novo](endpoint-novo.md) | apollo / fastapi / express + orfeu | ver endpoint-novo |
14
14
  | 3 | **Documento GraphQL** em `src/app/services/<dominio>/<dominio>.graphql` + `npm run codegen` com o GraphQL local de pé (gera `<dominio>.generated.ts`, commitado) | angular | `references/dados.md` |
15
15
  | 4 | **Service** `providedIn: 'root'` com `injectGraphqlClient` + `unwrap`; erro vira estado da tela | angular | `SKILL.md` "Dados", `references/dados.md` |
@@ -99,8 +99,11 @@ export function wsContextParams(
99
99
  import { RedisPubSub } from 'graphql-redis-subscriptions';
100
100
  import { Redis } from 'ioredis';
101
101
 
102
- function options() {
102
+ // Toda conexão nomeada (CLIENT SETNAME) por papel: `meuapp-graphql-publisher` / `-subscriber` no CLIENT LIST.
103
+ function options(role: 'publisher' | 'subscriber') {
104
+ const base = process.env.REDIS_CLIENT_NAME?.trim() || 'meuapp-graphql';
103
105
  return {
106
+ connectionName: `${base}-${role}`,
104
107
  host: process.env.REDIS_HOST,
105
108
  port: Number(process.env.REDIS_PORT ?? 6379),
106
109
  password: process.env.REDIS_PASSWORD || undefined,
@@ -120,8 +123,8 @@ let instance: RedisPubSub | undefined;
120
123
  /** Criado no primeiro uso: em escopo de módulo leria process.env antes do dotenv.config(). */
121
124
  export function getPubSub(): RedisPubSub {
122
125
  if (!instance) {
123
- const publisher = new Redis(options());
124
- const subscriber = new Redis(options());
126
+ const publisher = new Redis(options('publisher'));
127
+ const subscriber = new Redis(options('subscriber'));
125
128
  throttleErrors(publisher, 'publisher');
126
129
  throttleErrors(subscriber, 'subscriber');
127
130
  instance = new RedisPubSub({ publisher, subscriber });
@@ -133,9 +136,12 @@ export const channel = (name: string) => `${process.env.REDIS_CHANNEL_PREFIX ??
133
136
  ```
134
137
 
135
138
  - Instância Redis compartilhada → **prefixo de canal** por app, igual no publicador e no gateway.
139
+ - **Conexão sem `connectionName` é defeito** (acropole `arquitetura.md` §3.1): sem ele não dá para saber, no
140
+ `CLIENT LIST`/redis_exporter, quem abre as conexões. `REDIS_CLIENT_NAME` sobrescreve a base; o papel continua
141
+ sufixado. Um teste confere os dois nomes e a sobrescrita.
136
142
  - `REDIS_DB` diferente entre publicador e gateway = eventos que nunca chegam, sem erro. Redis Cluster só tem
137
143
  o db 0.
138
- - Para Cluster: `new Redis.Cluster(nodes, { redisOptions: { password } })` escolhido por variável
144
+ - Para Cluster: `new Redis.Cluster(nodes, { redisOptions: { password, connectionName } })` escolhido por variável
139
145
  (`REDIS_CLUSTER=true`, `REDIS_HOSTS=h1:p,h2:p`).
140
146
  - Sem o listener de `error`, Redis fora do ar em dev inunda o console com "Unhandled error event".
141
147
 
@@ -164,6 +164,7 @@ CMD ["node", "dist/index.js"]
164
164
  | `PLATFORM_SERVICE_URL` (ou `<SERVICO>_URL`) | `baseURL` dos módulos REST |
165
165
  | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_CHANNEL_PREFIX` | pub/sub; `REDIS_DB` próprio do app (nunca o mesmo de outro app no mesmo Redis), igual ao do server do app |
166
166
  | `REDIS_CLUSTER`, `REDIS_HOSTS` | modo cluster |
167
+ | `REDIS_CLIENT_NAME` | base do nome das conexões (`CLIENT SETNAME`), padrão `<app>-graphql`; o papel é sufixado (`-publisher`/`-subscriber`) — ver subscriptions.md |
167
168
  | `GRAPHQL_INTROSPECTION` | `true` só onde se roda o codegen |
168
169
 
169
170
  `.env.*` fora do git (`.gitignore`), com `.env.example` só com nomes. Variáveis que o gateway não usa (banco,
@@ -0,0 +1,153 @@
1
+ ---
2
+ name: auto-servico
3
+ description: MCP do auto-serviço do Argos (argos-mcp) — como configurar um agente de IA para administrar o auto-serviço de uma aplicação (rotas, roteamento/telas, grupos e membros, acesso às telas, aplicações backend e permissões por operação, auditoria) e como o agente deve usar as tools. Cada conexão usa um x-app-token pessoal preso a UMA aplicação, então é uma conexão MCP por aplicação. Use ao configurar o .mcp.json/`claude mcp add` para o Argos, ao escrever instruções (CLAUDE.md) para um agente que vai usar esse MCP, quando o pedido for publicar tela, dar acesso a alguém ou revisar permissões de uma aplicação com as tools do argos-mcp disponíveis, ou ao diagnosticar erro dessas tools. Não use para o código de uma tela (angular), para proteger endpoint (orfeu) nem para o painel central de administração do Argos.
4
+ ---
5
+
6
+ # auto-servico
7
+
8
+ O **argos-mcp** é um servidor MCP (Streamable HTTP, `POST <host>/argos/mcp`) que deixa um agente de IA fazer, por
9
+ tools, o mesmo que o administrador de uma aplicação faz na tela de auto-serviço do Argos. Ele não tem banco: toda
10
+ tool vira uma chamada ao `/auto-service` do argos-admin com o token do próprio agente, então valem as mesmas regras
11
+ da tela (rota de template intocável, rota protegida, recurso de outra aplicação = 404, auditoria).
12
+
13
+ Skills relacionadas: **orfeu** (o `x-app-token` e a auditoria do lado dos serviços), **angular** (a tela que usa
14
+ o `router_id` criado aqui), **hefesto** (deploy do próprio argos-mcp).
15
+
16
+ ## A regra que muda tudo: um token, uma aplicação
17
+
18
+ O agente se autentica com o **token de aplicação pessoal** (`x-app-token`, `argos_app_…`). O token é preso a:
19
+
20
+ - um **usuário** (as permissões são as dele, recalculadas a cada uso);
21
+ - uma **aplicação** (client): a aplicação em que a pessoa estava logada quando criou o token;
22
+ - um **nível** (badge) escolhido na criação. Para o MCP ele precisa ser **Administrador**.
23
+
24
+ O MCP administra **somente** a aplicação do token. Nenhuma tool recebe a aplicação como argumento; um
25
+ `client_id` mandado pelo agente é descartado. Consequência prática:
26
+
27
+ > **Uma conexão MCP por aplicação.** O nome da conexão diz qual aplicação ela administra, e a IA escolhe a
28
+ > aplicação escolhendo a conexão.
29
+
30
+ Não há "token para todas as aplicações". Isso é de propósito: limita o estrago de um token vazado ou de um
31
+ agente que confundiu a aplicação.
32
+
33
+ ## Configurar o cliente
34
+
35
+ ### 1. Criar um token por aplicação
36
+
37
+ Para cada aplicação, a pessoa (administradora dela):
38
+
39
+ 1. entra **na aplicação** pelo login do Argos (o token herda a aplicação da sessão);
40
+ 2. abre *Configurações › Tokens de aplicação*, escolhe o nível **Administrador**, um nome (ex.: `agente-ia`) e a
41
+ validade (até 365 dias);
42
+ 3. copia o valor: ele aparece **uma vez só**.
43
+
44
+ O MCP não cria nem renova tokens (um `x-app-token` não pode gerenciar tokens). Revogar na mesma tela derruba o
45
+ agente em até ~1–2 min (cache da validação do token).
46
+
47
+ ### 2. Uma conexão por aplicação, token em variável de ambiente
48
+
49
+ `.mcp.json` do projeto (Claude Code expande `${VAR}`; o token **nunca** vai para o arquivo nem para o git):
50
+
51
+ ```json
52
+ {
53
+ "mcpServers": {
54
+ "argos-vendas": {
55
+ "type": "http",
56
+ "url": "https://<host>/argos/mcp",
57
+ "headers": { "x-app-token": "${ARGOS_TOKEN_VENDAS}" }
58
+ },
59
+ "argos-compras": {
60
+ "type": "http",
61
+ "url": "https://<host>/argos/mcp",
62
+ "headers": { "x-app-token": "${ARGOS_TOKEN_COMPRAS}" }
63
+ },
64
+ "argos-compras-leitura": {
65
+ "type": "http",
66
+ "url": "https://<host>/argos/mcp",
67
+ "headers": { "x-app-token": "${ARGOS_TOKEN_COMPRAS}", "x-mcp-scopes": "autoservice.*.read" }
68
+ }
69
+ }
70
+ }
71
+ ```
72
+
73
+ Pela linha de comando: `claude mcp add --transport http argos-vendas https://<host>/argos/mcp --header "x-app-token: $ARGOS_TOKEN_VENDAS"`
74
+ (com `--scope project` grava no `.mcp.json`; sem, fica só para você).
75
+
76
+ - **Nome**: `argos-<aplicação>` (e `-leitura` para a variante só de consulta). As tools aparecem como
77
+ `mcp__argos-vendas__createRoute`: o prefixo deixa explícito onde cada ação cai.
78
+ - **Escopos**: `x-mcp-scopes` só **restringe** (nunca amplia). `autoservice.*.read` = agente de consulta;
79
+ lista completa em [references/tools.md](references/tools.md).
80
+ - **Clientes que não são navegador**: requisição com header `Origin` é recusada (403). Não use o MCP a partir de
81
+ uma página web.
82
+
83
+ ### 3. Instruções para o agente (CLAUDE.md do projeto)
84
+
85
+ O servidor já manda as regras gerais no `initialize`. O que é do **seu** ambiente vai no `CLAUDE.md`:
86
+
87
+ ```markdown
88
+ ## Auto-serviço do Argos (MCP)
89
+ - Uma conexão por aplicação: `argos-vendas`, `argos-compras`, ... Use a da aplicação pedida; se o pedido não
90
+ disser qual, pergunte. Nunca "tente na outra".
91
+ - Comece por `getContext` e confirme o nome da aplicação antes de alterar algo.
92
+ - Antes de tool destrutiva (delete*, revoke*, remove*), mostre o que muda e peça confirmação.
93
+ - Nunca remova o grupo administrador, o acesso dele ou o próprio usuário dele.
94
+ - Secret de `createApp`: entregue só ao usuário, uma vez; nunca repita nem grave em arquivo.
95
+ ```
96
+
97
+ ## Como o agente deve trabalhar
98
+
99
+ 1. **Escolha a conexão** pela aplicação pedida. Pedido ambíguo ("publica a tela de pedidos") com mais de uma
100
+ conexão disponível → pergunte qual aplicação.
101
+ 2. **`getContext` primeiro**: confirma aplicação, usuário, escopos e validade da sessão.
102
+ 3. **Leia antes de criar**: `listRoutes`/`getRoutingTree` (reaproveite rotas de nível superior), `listGroups`,
103
+ `listAccess`. Não invente ids: todo id vem de uma listagem.
104
+ 4. **Siga os roteiros** do próprio servidor (prompts `register-screen`, `onboard-user`, `access-review`) ou os de
105
+ [references/roteiros.md](references/roteiros.md).
106
+ 5. **Confirme o destrutivo** e **confira o efeito**: `listAuditEvents` com o `trace_id` devolvido em `_meta`.
107
+
108
+ ### Modelo do Argos em uma tabela
109
+
110
+ | Conceito | O que é | Tools |
111
+ | --- | --- | --- |
112
+ | Rota | Um trecho do endereço/menu (`name`, `icon`, `path` em minúsculas e hífen) | `listRoutes`, `createRoute`, `updateRoute`, `deleteRoute` |
113
+ | Router | A tela: composição de rotas em níveis header › navigation › menu › item › submenu › **page**; o id dele é o `router_id` que o front registra | `createRouter`, `updateRouter`, `getRoutingTree`, `reorderRouters` |
114
+ | Acesso | Um grupo entra na aplicação | `listAccess`, `grantGroupAccess`, `revokeGroupAccess` |
115
+ | Guard | Qual router (tela) o grupo daquele acesso vê | `listAccessGuards`, `addAccessGuard`, `removeAccessGuard` |
116
+ | Membro | Usuário do realm dentro de um grupo da aplicação | `searchUsers`, `addGroupMember`, `removeGroupMember` |
117
+ | App | Backend da aplicação (client_credentials) | `listApps`, `createApp`, `listAppOperations` |
118
+ | Consumer / permissão | Grupo vinculado a um backend / operação do backend liberada para ele | `addAppConsumer`, `grantPermission`, `revokePermission` |
119
+
120
+ Tela nova: **rota(s) → router**; router privado (`is_private`) só aparece para o grupo que tiver o **guard** dele.
121
+ Operação de backend só libera depois de **consumer → permissão**.
122
+
123
+ ### O que o MCP não faz (e o que dizer ao usuário)
124
+
125
+ - Alterar **outra** aplicação: precisa de outra conexão, com token criado nela.
126
+ - Editar rota/router **de template** (vem do template da aplicação) ou liberar rota **protegida**: só o painel
127
+ central do Argos.
128
+ - Criar/revogar tokens, mexer em realm, client, template ou tipo de grupo: painel central.
129
+ - Criar grupo novo: os grupos vêm vinculados à aplicação pelo painel; o MCP gerencia membros e permissões deles.
130
+
131
+ ## Erros
132
+
133
+ Toda falha vem como `{ "error": { "code", "message" } }` (resultado `isError` numa tool). Resumo; detalhes e
134
+ causas em [references/diagnostico.md](references/diagnostico.md):
135
+
136
+ | Código | Leitura rápida |
137
+ | --- | --- |
138
+ | `AUTHENTICATION_ERROR` | Token ausente, expirado, revogado ou dono desativado → novo token |
139
+ | `AUTHORIZATION_ERROR` | Token sem nível Administrador / grupo sem acesso, escopo restrito, ou recurso de template |
140
+ | `VALIDATION_ERROR` | Argumento inválido (`details.issues` diz qual) ou `path` fora do padrão |
141
+ | `RESOURCE_NOT_FOUND` | Id inexistente **ou de outra aplicação** (o servidor não distingue) |
142
+ | `CONFLICT` | Já existe (vínculo, permissão) ou rota protegida |
143
+ | `TIMEOUT` / `INTERNAL_ERROR` | argos-admin lento ou fora; tente de novo, depois veja `/argos/mcp/health` |
144
+
145
+ HTTP 404 com `Mcp-Session-Id` é **sessão expirada**, não erro de dado: o cliente MCP refaz o `initialize` sozinho.
146
+
147
+ ## Checklist
148
+
149
+ - [ ] Um token **por aplicação**, criado logado nela, nível **Administrador**, validade curta o bastante
150
+ - [ ] Uma conexão por aplicação, nome `argos-<aplicação>`, token em variável de ambiente (nada no git)
151
+ - [ ] Variante `-leitura` com `x-mcp-scopes: autoservice.*.read` quando o agente só consulta
152
+ - [ ] `CLAUDE.md` com o mapa conexão → aplicação e as regras de confirmação
153
+ - [ ] O agente começa por `getContext`, não inventa id e confere o efeito na auditoria
@@ -0,0 +1,42 @@
1
+ # Diagnóstico do argos-mcp
2
+
3
+ Formato de erro (MES): `{ "error": { "code", "message", "details"? } }`. Antes da sessão (credencial, sessão,
4
+ origem) vem no corpo HTTP; dentro de uma tool vem como resultado `isError: true`.
5
+
6
+ ## Ao conectar (HTTP)
7
+
8
+ | Sintoma | Causa | Ação |
9
+ | --- | --- | --- |
10
+ | 401 `AUTHENTICATION_ERROR` | Header ausente ou com nome errado (é `x-app-token`, não `Authorization`); token expirado, revogado; dono desativado | Confira o header e a variável de ambiente; crie outro token |
11
+ | 401 com token novo, aplicação de outro realm | O auth-server não lista o argos-mcp e o argos-admin em `INTROSPECT_ANY_REALM_APP_IDS` | Configuração da plataforma (quem administra o Argos) |
12
+ | 403 `AUTHORIZATION_ERROR` "nível Administrador" | Token criado com outro nível, ou o grupo da pessoa não tem acesso à aplicação | Crie o token logado na aplicação, escolhendo **Administrador** |
13
+ | 403 "token não identifica a aplicação" | Token sem aplicação (ex.: token de serviço) | Use um token pessoal (`argos_app_…`) |
14
+ | 403 "Origem não permitida" | Chamada de navegador (header `Origin`) | Use um cliente MCP de linha de comando/desktop |
15
+ | 400 `x-mcp-scopes inválido` | Caractere fora de `a-z . *` no header | Ex.: `autoservice.*.read` |
16
+ | 400 "Mcp-Session-Id obrigatório" | Cliente sem suporte a sessão do Streamable HTTP | Atualize o cliente MCP |
17
+ | 404 com `Mcp-Session-Id` | Sessão expirada (padrão 8 h, nunca além da validade do token), encerrada ou de outro token | Normal: o cliente refaz o `initialize` |
18
+ | 503 `INTERNAL_ERROR` "indisponível" | argos-admin fora ou inacessível pelo argos-mcp | `GET <host>/argos/mcp/health` mostra `admin`/`auth` |
19
+
20
+ ## Dentro de uma tool
21
+
22
+ | Código | Causas comuns | Ação |
23
+ | --- | --- | --- |
24
+ | `VALIDATION_ERROR` | Argumento faltando/errado (`details.issues[].path`); id que não é UUID; `path` com `/`, número ou acento; update sem nenhum campo | Corrija o argumento; ids vêm das listagens |
25
+ | `AUTHORIZATION_ERROR` + `details.missing` | Escopo restrito por `x-mcp-scopes` (conexão `-leitura`) | Use a conexão com escrita, se o usuário quiser |
26
+ | `AUTHORIZATION_ERROR` sem `missing` | Rota/router de **template**; liberar rota **protegida**; badge do grupo fora dos `allowed_type_ids` do router (`badge_not_allowed`) | Template e proteção: painel central. Badge: `updateRouter` com `allowed_type_ids` |
27
+ | `RESOURCE_NOT_FOUND` | Id inexistente **ou de outra aplicação** (a resposta é a mesma de propósito); grupo não vinculado à aplicação; usuário de outro realm | Liste de novo na conexão certa |
28
+ | `CONFLICT` | Vínculo/guard/permissão já existe; excluir rota protegida | Trate como "já feito"; proteção só no painel central |
29
+ | `TIMEOUT` | argos-admin demorou mais de 15 s | Tente de novo; persistindo, plataforma |
30
+ | `INTERNAL_ERROR` | Falha no admin ou resposta fora do contrato | Guarde o `_meta.trace_id` e passe para quem opera o Argos |
31
+
32
+ ## Conferir o que foi feito
33
+
34
+ `listAuditEvents` com `trace_id` (32 hex do `_meta`) mostra a ação inteira: o evento da requisição ao MCP
35
+ (`actor_type` `app_token`, com o nome da tool) e o evento de cada chamada ao auto-serviço. `getAuditTrace(trace_id)`
36
+ devolve a cadeia na ordem. Sem `from`/`to`, a janela é das últimas 24 h (máximo 31 dias).
37
+
38
+ ## Saúde do servidor
39
+
40
+ `GET <host>/argos/mcp/live` (processo), `/ready` e `/health` (argos-admin e argos-auth), `/manifest` (contratos),
41
+ `/metrics` (Prometheus: `mcp_tool_executions_total`, `mcp_tool_failures_total`, ...). Todos públicos e sem dado de
42
+ aplicação.
@@ -0,0 +1,63 @@
1
+ # Roteiros do auto-serviço pelo MCP
2
+
3
+ Sequências de tools para as tarefas comuns. Todas começam por `getContext` na conexão da aplicação certa e
4
+ terminam conferindo a auditoria (`listAuditEvents` com o `trace_id` do `_meta` da última tool). Ids sempre vêm de
5
+ uma listagem, nunca de suposição.
6
+
7
+ ## Publicar uma tela nova
8
+
9
+ Pedido típico: "publica a tela de Ordens de serviço no menu Operação, para o grupo Atendentes".
10
+
11
+ 1. `getRoutingTree` + `listRoutes`: ache o ponto do menu (ex.: a rota `operacao` no nível menu) e veja se a rota da
12
+ página já existe.
13
+ 2. `createRoute` para cada nível que faltar. `path` é **um trecho só**, minúsculas e hífen (`ordens-servico`);
14
+ `path` vazio = rota "pasta" (só agrupa o menu).
15
+ 3. `createRouter` com `page_id` = rota da página e os níveis acima (`menu_id`, ...). `is_private: true` quando só
16
+ quem tiver guard deve ver. `allowed_type_ids` restringe quais badges podem receber guard da tela.
17
+ 4. `listGroups` → id do grupo; `listAccess` → `access_id` dele. Sem acesso: `grantGroupAccess` (confirme antes:
18
+ dá entrada na aplicação inteira).
19
+ 5. `addAccessGuard(access_id, router_id)`.
20
+ 6. Entregue ao usuário o **`router_id`**: é o id que a tela Angular registra em `features.routes.ts` (skill
21
+ **angular**). O MCP cria o lado do Argos; o código da tela continua sendo do repositório do app.
22
+
23
+ Ordem no menu: `getRoutingTree` devolve os `router_ids` de cada nó; `reorderRouters` recebe, por nível, os ids na
24
+ ordem desejada.
25
+
26
+ ## Dar acesso a uma pessoa
27
+
28
+ 1. `searchUsers(search)` por nome, usuário ou e-mail. Mais de um resultado → pergunte qual.
29
+ 2. `listGroups` → o grupo certo (o tipo/badge dele diz o nível: Administrador, Usuário, ...).
30
+ 3. `addGroupMember(group_id, user_id, role?)`. Já membro → só atualiza o papel.
31
+ 4. Mostre o que a pessoa passa a ver: `listAccess` + `listAccessGuards` do acesso do grupo e, se houver backends,
32
+ `listAppConsumers`/`listConsumerPermissions`.
33
+
34
+ Tirar acesso é o inverso com `removeGroupMember` (destrutiva: confirme).
35
+
36
+ ## Liberar operações de um backend para um grupo
37
+
38
+ 1. `listApps` → `app_id`.
39
+ 2. `listAppOperations(app_id)` → as operações que o backend registrou (`identifier`, `method`, `level`) e o
40
+ `operation_id` de cada uma. Só existem as que o serviço declarou com o Orfeu (skill **orfeu**); se falta
41
+ operação, o problema é no código do serviço, não no Argos.
42
+ 3. `listAppConsumers(app_id)` → consumer do grupo; sem vínculo, `addAppConsumer(app_id, group_id)`.
43
+ 4. `grantPermission(consumer_id, operation_id)` para cada operação. Prefira liberar leitura e escrita
44
+ separadamente, conforme o papel do grupo.
45
+
46
+ ## Backend novo
47
+
48
+ `createApp(name)` devolve `id` e **`secret` uma única vez**. Entregue os dois ao usuário para o cofre/variáveis
49
+ do serviço (`APP_ID`/`APP_SECRET` do Orfeu) e não repita o secret depois. Em seguida, o serviço sobe, registra as
50
+ operações, e o roteiro acima libera as operações aos grupos.
51
+
52
+ ## Revisão de acesso (só leitura)
53
+
54
+ Use a conexão `-leitura` se existir. `listAccess` → para cada acesso, `listAccessGuards`; `listGroupMembers` de
55
+ cada grupo; `listApps` → `listAppConsumers` → `listConsumerPermissions`. Monte a tabela
56
+ grupo → membros → telas → operações e aponte excessos (grupo sem membro, tela sem guard, escrita liberada a grupo
57
+ de consulta). **Proponha**; não remova nada sem o usuário confirmar item a item.
58
+
59
+ ## Mais de uma aplicação no mesmo pedido
60
+
61
+ "Libera a tela X nas aplicações Vendas e Compras": faça o roteiro inteiro numa conexão, confira, e repita na
62
+ outra. Ids de uma aplicação **não** valem na outra (rotas, routers, grupos e acessos são por aplicação); nunca
63
+ reaproveite um id entre conexões.
@@ -0,0 +1,108 @@
1
+ # Tools, escopos e resources do argos-mcp
2
+
3
+ Tabela gerada do código do argos-mcp (contrato `1.0.0` de todas as tools). O contrato completo, com JSON Schema
4
+ draft 2020-12 de entrada e saída, sai do próprio servidor: `GET <host>/argos/mcp/manifest` (público) ou
5
+ `tools/list` numa sessão. Nenhuma tool recebe a aplicação: é sempre a do token.
6
+
7
+ Resultado de sucesso: `structuredContent` com o objeto do contrato (o mesmo JSON em `content[0].text`) e
8
+ `_meta.trace_id`/`span_id` para achar a ação na auditoria. Falha: `isError: true` e `{ error: { code, message,
9
+ details? } }` (ver [diagnostico.md](diagnostico.md)).
10
+
11
+ ## Identidade (contexto, grupos, membros)
12
+
13
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
14
+ | --- | --- | --- | --- |
15
+ | `getContext` | `autoservice.context.read` | leitura | — |
16
+ | `listGroups` | `autoservice.groups.read` | leitura | — |
17
+ | `searchUsers` | `autoservice.groups.read` | leitura | search, limit |
18
+ | `listGroupMembers` | `autoservice.groups.read` | leitura | **group_id** |
19
+ | `addGroupMember` | `autoservice.groups.write` | escrita | **group_id**, **user_id**, role |
20
+ | `updateGroupMemberRole` | `autoservice.groups.write` | escrita | **group_id**, **user_id**, **role** |
21
+ | `removeGroupMember` | `autoservice.groups.write` | **destrutiva** | **group_id**, **user_id** |
22
+
23
+ ## Rotas e roteamento
24
+
25
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
26
+ | --- | --- | --- | --- |
27
+ | `listRoutes` | `autoservice.routes.read` | leitura | — |
28
+ | `getRoute` | `autoservice.routes.read` | leitura | **route_id** |
29
+ | `createRoute` | `autoservice.routes.write` | escrita | **name**, display_name, **icon**, path, info, excludable |
30
+ | `updateRoute` | `autoservice.routes.write` | escrita | **route_id**, name, display_name, icon, path, info, excludable |
31
+ | `deleteRoute` | `autoservice.routes.write` | **destrutiva** | **route_id** |
32
+ | `listRouters` | `autoservice.routing.read` | leitura | — |
33
+ | `getRouter` | `autoservice.routing.read` | leitura | **router_id** |
34
+ | `getRoutingTree` | `autoservice.routing.read` | leitura | — |
35
+ | `createRouter` | `autoservice.routing.write` | escrita | **page_id**, header_id, navigation_id, menu_id, item_id, submenu_id, is_private, description, allowed_type_ids |
36
+ | `updateRouter` | `autoservice.routing.write` | escrita | **router_id**, page_id, header_id, navigation_id, menu_id, item_id, submenu_id, is_private, description, allowed_type_ids |
37
+ | `deleteRouter` | `autoservice.routing.write` | **destrutiva** | **router_id** |
38
+ | `reorderRouters` | `autoservice.routing.write` | escrita | **groups** |
39
+
40
+ ## Acesso, aplicações e permissões
41
+
42
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
43
+ | --- | --- | --- | --- |
44
+ | `listAccess` | `autoservice.access.read` | leitura | — |
45
+ | `grantGroupAccess` | `autoservice.access.write` | escrita | **group_id** |
46
+ | `revokeGroupAccess` | `autoservice.access.write` | **destrutiva** | **access_id** |
47
+ | `listAccessGuards` | `autoservice.access.read` | leitura | **access_id** |
48
+ | `addAccessGuard` | `autoservice.access.write` | escrita | **access_id**, **router_id** |
49
+ | `removeAccessGuard` | `autoservice.access.write` | **destrutiva** | **access_id**, **guard_id** |
50
+ | `listApps` | `autoservice.apps.read` | leitura | — |
51
+ | `getApp` | `autoservice.apps.read` | leitura | **app_id** |
52
+ | `createApp` | `autoservice.apps.write` | escrita | **name**, allowed_grants |
53
+ | `updateApp` | `autoservice.apps.write` | escrita | **app_id**, name, allowed_grants, enabled |
54
+ | `deleteApp` | `autoservice.apps.write` | **destrutiva** | **app_id** |
55
+ | `listAppOperations` | `autoservice.apps.read` | leitura | **app_id** |
56
+ | `listAppConsumers` | `autoservice.permissions.read` | leitura | **app_id** |
57
+ | `addAppConsumer` | `autoservice.permissions.write` | escrita | **app_id**, **group_id** |
58
+ | `removeAppConsumer` | `autoservice.permissions.write` | **destrutiva** | **consumer_id** |
59
+ | `listConsumerPermissions` | `autoservice.permissions.read` | leitura | **consumer_id** |
60
+ | `grantPermission` | `autoservice.permissions.write` | escrita | **consumer_id**, **operation_id** |
61
+ | `revokePermission` | `autoservice.permissions.write` | **destrutiva** | **consumer_id**, **permission_id** |
62
+
63
+ ## Auditoria
64
+
65
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
66
+ | --- | --- | --- | --- |
67
+ | `listAuditEvents` | `autoservice.audit.read` | leitura | from, to, app_id, user_id, operation, method, outcome, actor_type, trace_id, limit, cursor |
68
+ | `getAuditTrace` | `autoservice.audit.read` | leitura | **trace_id** |
69
+
70
+ ## Escopos
71
+
72
+ | Escopo | Permite |
73
+ | --- | --- |
74
+ | `autoservice.context.read` | Ver o client do token, o usuário e a sessão |
75
+ | `autoservice.routes.read` | Listar e ver rotas (telas) do client |
76
+ | `autoservice.routes.write` | Criar, editar e excluir rotas do client |
77
+ | `autoservice.routing.read` | Ver o roteamento (routers) e a árvore do menu |
78
+ | `autoservice.routing.write` | Criar, editar, reordenar e excluir routers |
79
+ | `autoservice.groups.read` | Listar grupos do client, membros e buscar usuários do realm |
80
+ | `autoservice.groups.write` | Adicionar, alterar papel e remover membros dos grupos do client |
81
+ | `autoservice.access.read` | Ver quais grupos acessam o client e quais telas cada um vê |
82
+ | `autoservice.access.write` | Conceder/revogar acesso de grupo ao client e às telas (guards) |
83
+ | `autoservice.apps.read` | Listar e ver as aplicações (backends) do client e suas operações |
84
+ | `autoservice.apps.write` | Criar, editar e excluir aplicações do client |
85
+ | `autoservice.permissions.read` | Ver consumers (grupo x aplicação) e as permissões por operação |
86
+ | `autoservice.permissions.write` | Vincular grupos às aplicações e conceder/revogar operações |
87
+ | `autoservice.audit.read` | Consultar a auditoria das aplicações do client |
88
+
89
+ `x-mcp-scopes` aceita lista (vírgula ou espaço) e curinga por segmento: `autoservice.*.read` (só leitura),
90
+ `autoservice.routes.*`, `autoservice.*`. Escopo desconhecido não amplia nada; caractere inválido = 400.
91
+
92
+ ## Resources
93
+
94
+ | URI | Conteúdo |
95
+ | --- | --- |
96
+ | `argos-autoservice://catalog` | Catálogo: tools, resources e prompts com versão, escopos e criticidade |
97
+ | `argos-autoservice://ownership` | Dono e contato do servidor |
98
+ | `argos-autoservice://dependencies` | Do que o MCP depende (argos-admin, argos-auth) |
99
+ | `argos-autoservice://runbooks` · `playbooks` | Diagnóstico e roteiros (o mesmo conteúdo desta skill, do lado do servidor) |
100
+ | `argos-autoservice://client/routes` · `routing-tree` · `groups` · `access` · `apps` | Dados vivos da aplicação do token |
101
+
102
+ ## Prompts
103
+
104
+ | Prompt | Argumentos | Para |
105
+ | --- | --- | --- |
106
+ | `register-screen` | **screen**, **path**, icon, group | Publicar uma tela |
107
+ | `onboard-user` | **user**, **group**, role | Dar acesso a uma pessoa |
108
+ | `access-review` | — | Revisão de acesso (só propõe, não altera) |
@@ -93,6 +93,8 @@ background no lifespan: cada worker do uvicorn roda o lifespan inteiro e a taref
93
93
  | Segredo visível em `ps aux` no host | `podman run -e SEGREDO=...` montado por código; use `--env-file` temporário |
94
94
  | `/bin/sh^M: bad interpreter` / `$'\r': command not found` | `.sh` com CRLF; falta `*.sh text eol=lf` no `.gitattributes` |
95
95
  | HEALTHCHECK ignorado com aviso no build | Podman/Buildah em formato OCI (padrão); só o formato `docker` grava |
96
+ | Podman no Windows: todo container falha com `controller pids is not available` | VM do WSL sem o controlador `pids`; ver `references/podman-local.md` |
97
+ | Podman no Windows: socket montado vira pasta vazia (`/mnt/c/run/...`) | compose rodado pelo cliente do Windows; rode dentro da VM (`references/podman-local.md`) |
96
98
 
97
99
  ## Índice de referências
98
100
 
@@ -100,3 +102,4 @@ background no lifespan: cada worker do uvicorn roda o lifespan inteiro e a taref
100
102
  | --- | --- |
101
103
  | `references/modelos.md` | Dockerfiles comentados: Angular (dev/build/site), Node (Express/Apollo), Node servindo SPA + API, Python (FastAPI, com e sem compilação); `.dockerignore` por stack |
102
104
  | `references/porques.md` | Cada decisão explicada: base, multi-stage, cache, `npm ci`, credenciais, segredo sem default, `--env-file`, nome que vira caminho, `.sh` em LF, sinais e PID 1, exec form, não-root, HEALTHCHECK, porta, ARG x ENV, `.dockerignore`, `timeout`, scratch no Angular, workers do uvicorn, Podman x Docker |
105
+ | `references/podman-local.md` | Subir as stacks com Podman Machine no Windows (WSL): cgroups, portas, compose dentro da VM, rede e DNS |