fg-tracker-mcp 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog — fg-tracker-mcp
 
+## 0.12.0
+
+Tools por permissão do token pessoal e escrita pelo MCP (PR B da proposta de tokens com permissões; a API e o painel vieram no PR #35). Requer a API com permissões por recurso (`credential.scopes` em `GET /v1/auth/me`, `API_KEY_PROJECT_MISMATCH`); nenhuma rota nova na API.
+
+- **Tools por permissão.** Com token `fgt_…`, o MCP lê `credential.scopes` ao iniciar (até 5 s) e só registra as tools que o token cobre (mapa em `src/permissions.ts`); token restrito a projetos não registra `tracker_create_project`. Sessão registra todas. Se a leitura falhar (API fora do ar, token revogado, API anterior às permissões), só as de leitura são registradas: falha de introspecção nunca libera escrita. `FG_TRACKER_READ_ONLY=1` continua valendo por cima. A API segue decidindo cada chamada.
+- **`tracker_status`**: diz qual credencial governa a escrita (sem valores), as permissões lidas no início × as de agora, as tools ocultas e o motivo, e pede para reiniciar o cliente MCP quando as permissões ou os projetos do token mudaram (a lista de tools só muda no reinício). `credential.scopes`, `permissions` e `writeCredential` no `structuredContent`.
+- **Sem fallback para a chave.** `loadtest_create_scenario` e `infra_discover` deixam de repetir a escrita com `FG_TRACKER_API_KEY` quando o token é recusado (401, 403 e, no discover, 404): com `FG_TRACKER_TOKEN`, a recusa é final. A chave só vale sem token, só nessas duas tools e só no projeto dela (o `projectId` vai no corpo; 400 `API_KEY_PROJECT_MISMATCH` vira "a chave é de outro projeto, nada foi gravado"; uma API anterior que grave no projeto da chave é detectada pelo `projectId` da resposta do roteiro). Cada requisição leva uma credencial só: a chave não viaja mais nas chamadas do Bearer.
+- **403 claros** pelo `code` da API: permissão que falta (`falta a permissão "Monitores: excluir" neste token`), operação só do painel, papel (`seu papel neste projeto é viewer`), projeto fora do token, token restrito criando projeto e falta de associação. Mensagens de erro mascaram `stk_…`/`fgt_…`.
+- **Tools novas** (sem alias `track_*`):
+  - issues: `tracker_update_issue` (resolver, "resolver no próximo release", ignorar até data ou até escalar, reabrir, atribuir com o membro conferido antes, priorizar) e `tracker_list_members` (sem telefone);
+  - monitores: `tracker_create_monitor`, `tracker_update_monitor` (pausar, agenda, ambiente do monitor antigo antes do 1º check-in), `tracker_run_monitor`, `tracker_delete_monitor`;
+  - alertas: `tracker_list_alert_rules` (com a severidade mínima por canal), `tracker_create_alert_rule`, `tracker_update_alert_rule` (config mesclada com a gravada), `tracker_delete_alert_rule`, `tracker_ack_alert_event`, `tracker_update_alert_delivery`;
+  - projeto: `tracker_update_project` (limiares, repositório, regras de dono com `memberId` conferido — `addOwnershipRules`/`removeOwnershipRules` mesclam com a lista completa da API, `ownershipRules` substitui —, autoatribuição; `tracker_update_allowed_origins` continua) e `tracker_delete_project`;
+  - `tracker_delete_sourcemaps`; `loadtest_update_scenario`, `loadtest_delete_scenario`, `loadtest_stop_run`; `infra_update_finding`, `infra_delete_connection`.
+- **Exclusões**: `destructiveHint: true` e `confirm` obrigatório com o nome ou slug do recurso (texto, nunca booleano), conferido contra o recurso lido na API antes do DELETE; a descrição manda perguntar ao usuário antes. O cliente HTTP recusa caminhos com segmento `.` ou `..` (o `fetch` os normalizaria para outra rota: `…/sourcemaps/..` viraria a exclusão do projeto), e `tracker_delete_sourcemaps` recusa essas releases e apaga também releases fora das 100 que a API lista.
+- `infra_validate` passa a mostrar o id de cada achado aberto (texto e `findings`) e `infra_get_diagram` o de cada conexão (texto e `connections`), para `infra_update_finding` e `infra_delete_connection`.
+- `tracker_list_alert_rules` respeita `FG_TRACKER_MAX_ITEMS` (`total`, `returned`, `truncated`).
+- `tracker_list_environments` passa a declarar também `releases:read` (lê `/release-environments`).
+- Documentação: tokens `fgt_` com as permissões necessárias, modelos do painel, precedência de credenciais, edição e reinício; a instalação recomendada deixa de pôr `FG_TRACKER_READ_ONLY=1` por padrão (continua como opção de só leitura).
+- `tools/list` (sessão): 87 tools e ~168 KB no padrão, 66 e ~139 KB sem aliases; token Agente MCP sem aliases, 47 e ~108 KB; Somente leitura sem aliases, 34 e ~84 KB.
+- Testes: registro por permissão, sessão, `FG_TRACKER_READ_ONLY`, introspecção que falha, suficiência de cada tool contra o mapa de rotas da API, permissão reduzida depois de iniciar, papel viewer, projetos restritos, exclusões com `confirm` errado e certo, nenhuma rota da chave com token recusado (401, 403, 404) e modo só com a chave; E2E com a API real em `apps/api/test/mcp-permissions.cases.cjs`.
+
+## 0.11.0
+
+Diagnóstico sem painel (revisão de 15/10/2026, T3). Todas as ferramentas novas usam rotas de leitura com `@ReadScope()` (funcionam com token pessoal `fgt_…`). As de janela absoluta, ordenação e comparação dependem da API desta mesma entrega (CONTRATO §4 "Janelas absolutas" e "Comparação", §18); com uma API anterior elas avisam (`windowIgnored`, `filtersApplied: false`, "API ignorou sort") ou explicam o caminho alternativo, e as demais continuam funcionando.
+
+- **Saída estruturada:** toda ferramenta de leitura declara `outputSchema` e devolve `structuredContent` validado contra ele; o texto continua o de antes (resumo + JSON). Onde o JSON era um array (`tracker_list_endpoints`, `tracker_list_releases`), o `structuredContent` é `{ items, … }`. Respostas com janela trazem `window: { from, to }`.
+- **Evidência e links:** as ferramentas de análise devolvem `evidence[]` (`traceId`, `spanId?`, `metric`, `value`, `window`, `note?`) só com traces que a API devolveu — no detalhe do trace, a raiz, os buracos sem span, os spans de I/O mais lentos, os repetidos e os que falharam (com o serviço). `links.dashboard` e blocos `resource_link` para o painel (`FG_TRACKER_WEB_URL` ou derivado da API) e para os novos recursos `fg-tracker://trace/{traceId}` e `fg-tracker://issue/{issueId}` (`?projectId=` opcional).
+- **Ferramentas novas** (sem alias `track_*`): `tracker_compare` (abaixo), `tracker_get_endpoint` (`/endpoints/detail`), `tracker_list_queries` (`/database`, com `env`/`service`, busca no SQL e um trace + span real da execução mais lenta de cada query), `tracker_log_stats` (`/logs/histogram` + `/logs/facets`), `tracker_list_alert_events` (`/alerts/events`, filtros por tipo, severidade, estado e janela; destinatários mascarados) e `tracker_list_environments` (`/release-environments` + ambientes e serviços do overview).
+- `tracker_search_logs` aceita `from`/`to` ISO 8601 (até 31 dias, validado antes da chamada).
+- **Janelas absolutas:** `tracker_get_overview`, `tracker_list_endpoints`, `tracker_get_endpoint`, `tracker_list_traces`, `tracker_list_queries` e `tracker_list_providers` aceitam `from`/`to` e conferem a janela que a API aplicou (cabeçalho `x-fg-tracker-window`).
+- **`tracker_compare`** (`GET …/compare`): duas janelas ou duas releases — latência total e por rota, decomposição do tempo por execução por tipo de span e spans que mais cresceram, com `evidence`. Cada lado declara `coverage` de spans brutos (retenção); sem eles a latência vem dos rollups e `decomposition` é `null`.
+- `tracker_list_traces`: `sort: "duration"`, `rootKind: "browser"` e `hasSpan: { kind?, service?, status?, name? }` (traces com algum span — inclusive filho ou de outro serviço — que case).
+- `tracker_get_monitor`: `from`/`to`, horário esperado e atraso (`delayMs`) de cada execução de job e `schedule.overdueMs`.
+- **M01:** `tracker_endpoint_history` não esconde mais o período recente: `points` é amostrado em 48 pontos com o primeiro e o último (antes, os 25 mais antigos), `markers` traz os 25 deploys mais recentes; aceita `service`/`env`. Todas as séries passam a incluir o último ponto na amostragem.
+- **M02:** `tracker_verify_ingest` procura qualquer raiz (`rootKind=all`): projeto só de jobs ou de navegador não recebe mais "NENHUM trace".
+- **M03:** dicas de erro por tipo de credencial: 401 com token pessoal (crie outro), 401 com sessão (prefira um token de leitura), 403 `TOKEN_SCOPE_INSUFFICIENT` (o token é somente leitura) distinto de 403 por falta de acesso ao projeto.
+- **M04:** `apiKey` vazia (token de leitura) é tratada como ausente: o guia usa o placeholder e explica onde copiar a chave, e `tracker_list_projects` diz que a chave não foi devolvida.
+- **M05:** `infra_plan_handover` deixa de se declarar somente leitura (faz POST numa rota de sessão).
+- **Segurança:** `FG_TRACKER_READ_ONLY=1` registra só as ferramentas com `readOnlyHint: true`; `tracker_status` mostra o tipo de credencial (token pessoal ou sessão), a validade, o modo somente leitura e avisa quando é sessão. A documentação recomenda `fgt_` + `FG_TRACKER_READ_ONLY=1`.
+- **Prompts das cinco jornadas:** `investigar-regressao-p95`, `investigar-query-lenta`, `investigar-job-atrasado`, `investigar-erro-distribuido` (API → serviço) e `confirmar-correcao`, com a sequência de ferramentas (≤ 6 chamadas), o critério de parada e a regra de citar a evidência.
+- Aliases `track_*`: continuam para os 21 nomes da 0.10, com o mesmo resultado (inclusive `structuredContent`), mas sem repetir o `outputSchema` no `tools/list`.
+- `tools/list`: 67 ferramentas (~130 KB) no padrão; 32 (~79 KB) com `FG_TRACKER_READ_ONLY=1` e `FG_TRACKER_LEGACY_TOOL_NAMES=0` (recomendado).
+- Testes pelo transporte MCP (cliente em memória, sem `_registeredTools`); `npm test` compila antes. E2E das jornadas contra a API real (`apps/api/test/mcp-journeys.cases.cjs`).
+
 ## 0.10.0
 
 Reúne o que entrou na `main` desde a 0.9.1 (PRs #11, #12, #13, #15) e a renomeação para FG Tracker. Requer a API com filtros de issues por cursor (PR #12), raízes `custom` (PR #15) e ambientes de monitores e releases (PR #14); com uma API anterior, os parâmetros novos são ignorados ou geram aviso, e as ferramentas antigas continuam funcionando.

package/README.md

@@ -1,6 +1,6 @@
 # fg-tracker-mcp
 
-Servidor [MCP](https://modelcontextprotocol.io) (stdio) do FG Tracker para agentes de código (Claude Code, Cursor, Windsurf, Claude Desktop): projetos, métricas, traces, issues com commits suspeitos, releases, monitores, provedores externos, logs e guia de instrumentação. Documentação completa: `docs/mcp.md` no repositório.
+Servidor [MCP](https://modelcontextprotocol.io) (stdio) do FG Tracker para agentes de código (Claude Code, Cursor, Windsurf, Claude Desktop): projetos, métricas, traces, issues com commits suspeitos, releases, monitores, provedores externos, logs, slow queries, eventos de alerta e guia de instrumentação, com respostas estruturadas (`structuredContent`) e evidência verificável para diagnosticar sem o painel — e, com as permissões do token, triagem de issues, monitores, regras de alerta e configurações do projeto. Documentação completa: `docs/mcp.md` no repositório.
 
 ## Instalação
 
@@ -9,7 +9,8 @@ Claude Code:
 ```bash
 claude mcp add fg-tracker \
   -e FG_TRACKER_URL=http://localhost:4050 \
-  -e FG_TRACKER_TOKEN=fgt_<seu_token_de_leitura> \
+  -e FG_TRACKER_TOKEN=fgt_<seu_token> \
+  -e FG_TRACKER_LEGACY_TOOL_NAMES=0 \
   -- npx -y fg-tracker-mcp
 ```
 
@@ -23,14 +24,15 @@ Cursor / Windsurf / Claude Desktop (JSON):
       "args": ["-y", "fg-tracker-mcp"],
       "env": {
         "FG_TRACKER_URL": "http://localhost:4050",
-        "FG_TRACKER_TOKEN": "fgt_<seu_token_de_leitura>"
+        "FG_TRACKER_TOKEN": "fgt_<seu_token>",
+        "FG_TRACKER_LEGACY_TOOL_NAMES": "0"
       }
     }
   }
 }
 ```
 
-Gere o token em **Conectar → Usar MCP → Gerar token de leitura para o MCP** (ou em **Conta → Tokens de acesso**). Ele só lê; para o agente criar projetos, registrar releases, mexer em infraestrutura ou iniciar testes de carga, use a configuração com a sessão. Detalhes em `docs/mcp.md` → Token de leitura.
+Gere o token em **Conectar → Usar MCP → Gerar token para o MCP** (ou em **Conta → Tokens de acesso**) e marque só o que o agente precisa: o modelo **Agente MCP** lê tudo e cria e edita projetos, issues, releases, monitores e alertas, sem excluir; **Somente leitura** serve para diagnóstico; exclusões, infraestrutura AWS e testes de carga entram pela matriz (ou **Acesso total**). O MCP lê as permissões do token ao iniciar (`GET /v1/auth/me`) e só registra as tools que elas cobrem; a API confere cada chamada, dentro do seu papel em cada projeto. **Editou as permissões? Reinicie o cliente MCP** para a lista de tools mudar (`tracker_status` avisa). Para nunca expor escrita, acrescente `FG_TRACKER_READ_ONLY=1`. Detalhes em `docs/mcp.md` → Token pessoal.
 
 Em produção, `FG_TRACKER_URL` é a URL da API mostrada no painel em **Conectar**. O endereço de produção da API é `https://tracker-api.fortground.com.br` (o antigo `track-api.fortground.com.br` continua respondendo).
 
@@ -39,15 +41,22 @@ Em produção, `FG_TRACKER_URL` é a URL da API mostrada no painel em **Conectar
 | variável | default | uso |
 |---|---|---|
 | `FG_TRACKER_URL` | `http://localhost:4050` | URL base da API |
-| `FG_TRACKER_TOKEN` | — | `Authorization: Bearer`: token pessoal de leitura `fgt_…` (painel → Conta → Tokens de acesso; não cai com logout) ou token de sessão, necessário só para as tools que escrevem — projetos, métricas, traces, issues, logs |
-| `FG_TRACKER_API_KEY` | — | chave de projeto (`x-fg-tracker-key`) — opcional, só ingestão |
+| `FG_TRACKER_TOKEN` | — | `Authorization: Bearer`: token pessoal `fgt_…` com as permissões necessárias (painel → Conta → Tokens de acesso; não cai com logout) ou token de sessão — projetos, métricas, traces, issues, logs e toda escrita |
+| `FG_TRACKER_API_KEY` | — | chave de projeto (`x-fg-tracker-key`) — opcional; só sem `FG_TRACKER_TOKEN`, `loadtest_create_scenario` e `infra_discover` gravam por ela, no projeto dela. Com token, nunca é usada |
 | `FG_TRACKER_TIMEOUT_MS` | `15000` | timeout das chamadas HTTP |
 | `FG_TRACKER_MAX_ITEMS` | `200` | teto de itens da lista principal de cada tool (1 a 1000) |
+| `FG_TRACKER_READ_ONLY` | desligado | `1`: só as tools de leitura (`readOnlyHint: true`) são registradas, mesmo com um token que escreve |
+| `FG_TRACKER_WEB_URL` | derivada da API | URL do painel nos links das respostas (`tracker-api.*` → `tracker.*`) |
+| `FG_TRACKER_LEGACY_TOOL_NAMES` | ligado | `0` desliga os aliases obsoletos `track_*` |
 
 Os nomes antigos `STREAD_TRACK_*` continuam lidos quando o nome novo está ausente.
 
 ## Tools, prompt e resource
 
+Escrita (0.12): `tracker_update_issue` e `tracker_list_members` (triagem: resolver, "resolver no próximo release", ignorar, atribuir, priorizar), `tracker_create_monitor`, `tracker_update_monitor`, `tracker_run_monitor`, `tracker_delete_monitor`, `tracker_list_alert_rules`, `tracker_create_alert_rule`, `tracker_update_alert_rule`, `tracker_delete_alert_rule`, `tracker_ack_alert_event`, `tracker_update_alert_delivery`, `tracker_update_project`, `tracker_delete_project`, `tracker_delete_sourcemaps`, `loadtest_update_scenario`, `loadtest_delete_scenario`, `loadtest_stop_run`, `infra_update_finding` e `infra_delete_connection`. Toda exclusão tem `destructiveHint: true` e exige `confirm` com o nome ou slug do recurso, conferido antes do DELETE. Com `FG_TRACKER_TOKEN`, a recusa do token é final (sem nova tentativa pela chave `stk_`). Detalhes em `docs/mcp.md` → Escrita e exclusões.
+
+Diagnóstico (0.11): toda tool de leitura tem `outputSchema` e devolve `structuredContent` (o texto continua igual); as de análise trazem `evidence[]` (`traceId`, `spanId?`, métrica, valor e janela) apontando para traces existentes, mais links para o painel e para os recursos `fg-tracker://trace/{traceId}` e `fg-tracker://issue/{issueId}`. Tools novas: `tracker_compare` (duas janelas ou releases: onde o tempo cresceu, com cobertura de spans brutos), `tracker_get_endpoint` (detalhe e traces mais lentos de uma rota), `tracker_list_queries` (slow queries com o trace e o span da execução mais lenta), `tracker_log_stats` (histograma e facetas de logs), `tracker_list_alert_events` (histórico de alertas, destinatários mascarados) e `tracker_list_environments`; métricas, traces e logs aceitam `from`/`to` ISO; `tracker_list_traces` ordena por duração e filtra por span filho (`hasSpan`); `tracker_get_monitor` mostra o atraso de cada execução. Prompts das jornadas: `investigar-regressao-p95`, `investigar-query-lenta`, `investigar-job-atrasado`, `investigar-erro-distribuido` e `confirmar-correcao`. Detalhes em `docs/mcp.md` → Saída estruturada e Jornadas de diagnóstico.
+
 Tools `tracker_*` (até a 0.9, `track_*`), prompt `instrument-project` e resource `fg-tracker://docs/quickstart`. Os nomes `track_*` continuam registrados como aliases obsoletos (a versão seguinte os desliga por padrão e a 1.0 os remove); `FG_TRACKER_LEGACY_TOOL_NAMES=0` deixa só os nomes novos.
 
 Infraestrutura AWS (0.6.0): tools `infra_*` e prompt `connect-infrastructure` — detectar contas/ambientes/regiões nas credenciais locais, conectar cada ambiente, descobrir recursos com credenciais locais (somente leitura), analisar o IaC, instrumentar, validar e gerar o PR de transferência de controle. Nenhuma tool altera recursos na AWS. Detalhes em `docs/mcp.md` → Infraestrutura.
@@ -61,11 +70,14 @@ Simulação de ambiente (0.8.0): prompt `create-load-test` e tools `loadtest_*`
 | tool | entrada | o que faz |
 |---|---|---|
 | `loadtest_scan_routes` | `{ path?, format? }` | local, somente leitura: rotas NestJS/Express/Next.js (método, caminho, arquivo:linha, controller, DTO, protegida?) e pistas de autenticação |
-| `loadtest_create_scenario` | `{ projectId, scenario, description? }` | valida o roteiro (§28.2, erros com caminho do campo) e grava (`POST /v1/projects/:id/loadtest/scenarios`, ou `POST /v1/loadtest/scenarios` só com `FG_TRACKER_API_KEY`); resumo com passos, variáveis extraídas, checks e avisos de efeitos externos |
+| `loadtest_create_scenario` | `{ projectId, scenario, description? }` | valida o roteiro (§28.2, erros com caminho do campo) e grava (`POST /v1/projects/:id/loadtest/scenarios` com o token, cuja recusa é final; `POST /v1/loadtest/scenarios` só quando não há `FG_TRACKER_TOKEN`, no projeto da chave); resumo com passos, variáveis extraídas, checks e avisos de efeitos externos |
+| `loadtest_update_scenario` | `{ projectId, scenarioId, name?, description?, scenario? }` | atualiza o roteiro (documento validado antes do `PUT`) |
+| `loadtest_delete_scenario` | `{ projectId, scenarioId, confirm }` | exclui o roteiro; `confirm` = nome |
 | `loadtest_list_scenarios` | `{ projectId }` | roteiros do projeto |
 | `loadtest_suggest_plan` | `{ preset, vus?, targetRps?, duration? }` | puro: plano k6 (§28.3) para smoke/load/stress/spike/soak/breakpoint |
 | `loadtest_get_run` | `{ projectId, runId, generateAdvice? }` | resumo do run: latências, erros, checks, thresholds, por passo e sugestões da IA |
 | `loadtest_start_run` | `{ projectId, scenarioId, baseUrl, connectionId, plan, credentialId?, environment?, confirm }` | gera carga real: recusa sem `confirm: true` e devolve o texto de confirmação (ambiente, baseUrl, pico de VUs/RPS, duração); prefira iniciar pela UI |
+| `loadtest_stop_run` | `{ projectId, runId }` | para a simulação (na fila, aborta; rodando, os executores param no próximo relatório) |
 
 ## Migração de stread-track-mcp
 

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 /**
  * Entrada do binário `fg-tracker-mcp` (alias obsoleto: `stread-track-mcp`): sobe o servidor MCP em stdio.
- * Env: FG_TRACKER_URL (default http://localhost:4050), FG_TRACKER_TOKEN, FG_TRACKER_API_KEY,
- * FG_TRACKER_TIMEOUT_MS — os nomes legados STREAD_TRACK_* continuam valendo como fallback.
+ * Env: FG_TRACKER_URL (default http://localhost:4050), FG_TRACKER_TOKEN (fgt_… com permissões, ou sessão), FG_TRACKER_API_KEY,
+ * FG_TRACKER_TIMEOUT_MS, FG_TRACKER_READ_ONLY, FG_TRACKER_WEB_URL — os nomes legados STREAD_TRACK_*
+ * continuam valendo como fallback.
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { configFromEnv, TrackClient } from './client.js';
-import { createServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+import { resolveToolAccess } from './permissions.js';
+import { createServer, readOnlyFromEnv, SERVER_NAME, SERVER_VERSION } from './server.js';
 const argv = process.argv.slice(2);
 if (argv.includes('--help') || argv.includes('-h')) {
     process.stdout.write([
@@ -17,14 +19,18 @@ if (argv.includes('--help') || argv.includes('-h')) {
         '',
         'Variáveis de ambiente:',
         '  FG_TRACKER_URL         URL da API (default http://localhost:4050)',
-        '  FG_TRACKER_TOKEN       token de sessão (Authorization: Bearer) — projetos, métricas, logs',
-        '  FG_TRACKER_API_KEY     chave de projeto (x-fg-tracker-key) — opcional, só ingestão',
+        '  FG_TRACKER_TOKEN       token pessoal fgt_… (painel → Conta → Tokens de acesso) com as permissões necessárias, ou sessão (Authorization: Bearer).',
+        '                         Com token pessoal, só as ferramentas que as permissões dele cobrem são registradas (lidas ao iniciar; reinicie ao editar o token)',
+        '  FG_TRACKER_API_KEY     chave de projeto (x-fg-tracker-key) — opcional; sem FG_TRACKER_TOKEN, grava roteiros e snapshots só no projeto dela',
         '  FG_TRACKER_TIMEOUT_MS  timeout das chamadas HTTP (default 15000)',
+        '  FG_TRACKER_READ_ONLY=1 só registra ferramentas de leitura (esconde toda ferramenta que cria, edita ou exclui), mesmo com permissões de escrita',
+        '  FG_TRACKER_WEB_URL     URL do painel para os links (default: derivada de FG_TRACKER_URL, ex. tracker-api.* → tracker.*)',
         '  FG_TRACKER_LEGACY_TOOL_NAMES=0  não registra os aliases obsoletos track_* das ferramentas tracker_*',
         '  (os nomes antigos STREAD_TRACK_* ainda são lidos como fallback; serão removidos na 1.0)',
         '',
         'Instalação no Claude Code:',
-        '  claude mcp add fg-tracker -e FG_TRACKER_URL=http://localhost:4050 -e FG_TRACKER_TOKEN=... -- npx -y fg-tracker-mcp',
+        '  claude mcp add fg-tracker -e FG_TRACKER_URL=http://localhost:4050 -e FG_TRACKER_TOKEN=fgt_... -- npx -y fg-tracker-mcp',
+        '  (só diagnóstico, sem nenhuma escrita: acrescente -e FG_TRACKER_READ_ONLY=1)',
         '',
     ].join('\n'));
     process.exit(0);
@@ -35,13 +41,22 @@ if (argv.includes('--version') || argv.includes('-v')) {
 }
 const config = configFromEnv();
 const client = new TrackClient(config);
-const server = createServer({ client });
+// Permissões do token antes de registrar as ferramentas (GET /v1/auth/me, até 5 s). Falha =
+// só as de leitura; a API continua decidindo cada chamada.
+const access = await resolveToolAccess(client);
+const server = createServer({ client, access });
 // stdout é o canal JSON-RPC: qualquer diagnóstico vai para stderr.
 const invoked = process.argv[1]?.split(/[\\/]/).pop() ?? '';
 if (invoked.startsWith('stread-track-')) {
     console.error(`[fg-tracker-mcp] "${invoked}" está obsoleto: use "fg-tracker-mcp" (o alias será removido na 1.0).`);
 }
-console.error(`[fg-tracker-mcp] API ${config.baseUrl} · token ${config.token ? 'ok' : 'ausente'} · apiKey ${config.apiKey ? 'ok' : 'ausente'}`);
+const credential = {
+    token: `pessoal (${access.scopes?.length ?? 0} permissões)`,
+    'token-unverified': `pessoal (permissões não lidas: só leitura${access.error ? `; ${access.error}` : ''})`,
+    session: 'de sessão (faz tudo o que você faz no painel; prefira um fgt_ com só o necessário)',
+    none: 'ausente',
+}[access.mode];
+console.error(`[fg-tracker-mcp] API ${config.baseUrl} · token ${credential} · apiKey ${config.apiKey ? (client.hasToken ? 'definida (não usada: o token decide)' : 'ok') : 'ausente'}${readOnlyFromEnv() ? ' · somente leitura' : ''}`);
 const transport = new StdioServerTransport();
 await server.connect(transport);
 const shutdown = () => {

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;GAIG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB;QACE,GAAG,WAAW,QAAQ,cAAc,uCAAuC;QAC3E,EAAE;QACF,uFAAuF;QACvF,+BAA+B;QAC/B,EAAE;QACF,wBAAwB;QACxB,qEAAqE;QACrE,6FAA6F;QAC7F,sFAAsF;QACtF,oEAAoE;QACpE,uGAAuG;QACvG,2FAA2F;QAC3F,EAAE;QACF,4BAA4B;QAC5B,sHAAsH;QACtH,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AACD,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;AAC/B,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;AACvC,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;AAExC,mEAAmE;AACnE,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;AAC5D,IAAI,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;IACxC,OAAO,CAAC,KAAK,CAAC,qBAAqB,OAAO,uEAAuE,CAAC,CAAC;AACrH,CAAC;AACD,OAAO,CAAC,KAAK,CAAC,wBAAwB,MAAM,CAAC,OAAO,YAAY,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,aAAa,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;AAEhJ,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAEhC,MAAM,QAAQ,GAAG,GAAS,EAAE;IAC1B,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC,CAAC;AACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -1,8 +1,12 @@
 /**
  * Cliente HTTP mínimo para a API do FG Tracker (docs/CONTRATO.md §4, §8, §11).
- * Lê `FG_TRACKER_URL`, `FG_TRACKER_TOKEN` (Bearer de sessão), `FG_TRACKER_API_KEY`
- * (chave de projeto, header `x-fg-tracker-key`) e `FG_TRACKER_TIMEOUT_MS` — com
+ * Lê `FG_TRACKER_URL`, `FG_TRACKER_TOKEN` (Bearer: token pessoal `fgt_…` com as permissões
+ * marcadas no painel, ou token de sessão), `FG_TRACKER_API_KEY` (chave de projeto, header
+ * `x-fg-tracker-key`), `FG_TRACKER_TIMEOUT_MS` e `FG_TRACKER_WEB_URL` — com
  * fallback para os nomes legados `STREAD_TRACK_*` (`stread-track-mcp` ≤ 0.3).
+ *
+ * Cada requisição leva uma credencial só: o Bearer nas rotas de usuário (o padrão) e a chave
+ * apenas nas rotas da chave (`auth: 'key'`), que as ferramentas só usam sem FG_TRACKER_TOKEN.
  */
 /** API local do monorepo. Em produção a API é `https://tracker-api.fortground.com.br`. */
 export declare const DEFAULT_URL = "http://localhost:4050";
@@ -18,33 +22,106 @@ export interface TrackClientConfig {
     token?: string;
     apiKey?: string;
     timeoutMs?: number;
+    /** URL do painel, para links (`FG_TRACKER_WEB_URL`; default derivado de `baseUrl`). */
+    webUrl?: string;
 }
 export type QueryValue = string | number | boolean | undefined | null;
+/** Campos de uma recusa 403 da API (CONTRATO.md §8.1, "Erros"). */
+export interface ApiErrorDetails {
+    requiredScope?: string | null;
+    requiredPermission?: string | null;
+    sessionOnly?: boolean;
+    role?: string;
+    requiredRoles?: string[];
+}
 export declare class TrackApiError extends Error {
     readonly status: number | undefined;
     readonly path: string;
     readonly hint?: string | undefined;
-    constructor(message: string, status: number | undefined, path: string, hint?: string | undefined);
+    /** `code` do corpo de erro da API (ex.: TOKEN_SCOPE_INSUFFICIENT), quando houver. */
+    readonly code?: string | undefined;
+    readonly details: ApiErrorDetails;
+    constructor(message: string, status: number | undefined, path: string, hint?: string | undefined, 
+    /** `code` do corpo de erro da API (ex.: TOKEN_SCOPE_INSUFFICIENT), quando houver. */
+    code?: string | undefined, details?: ApiErrorDetails);
     /** Mensagem amigável pronta para devolver ao agente. */
     describe(): string;
 }
 export declare function configFromEnv(env?: NodeJS.ProcessEnv): TrackClientConfig;
+/**
+ * Painel que acompanha a API: `tracker-api.<domínio>` → `tracker.<domínio>` (o alias antigo
+ * `track-api` também), `localhost:4050` → `localhost:3050`. Sem regra conhecida, `null`:
+ * as ferramentas deixam de mandar links do painel, nunca inventam um.
+ */
+export declare function webUrlFor(baseUrl: string): string | null;
+/** Cabeçalho com a janela absoluta (`from`/`to`) que a API aplicou (CONTRATO.md §4). */
+export declare const WINDOW_HEADER = "x-fg-tracker-window";
+/** Cabeçalho com os parâmetros extras que a rota aplicou (ex.: `traces-sort,traces-has-span`). */
+export declare const CAPABILITIES_HEADER = "x-fg-tracker-capabilities";
+/** Prefixo dos tokens pessoais (CONTRATO.md §8.1). */
+export declare const ACCESS_TOKEN_PREFIX = "fgt_";
+/**
+ * Esconde valores de credencial num texto que vai para o agente: chave de projeto `stk_…` e
+ * token pessoal `fgt_…`. As mensagens de erro da API não ecoam segredos; isto é a segunda linha.
+ */
+export declare function redactSecrets(value: string): string;
+/** Tipo da credencial de `FG_TRACKER_TOKEN`, pelo prefixo (sem chamar a API). */
+export type CredentialKind = 'access_token' | 'session' | 'none';
+/**
+ * Segmento "." ou ".." (também `%2e`) num caminho: o `fetch` (WHATWG URL) o normaliza e a
+ * requisição vai para outra rota — `DELETE …/sourcemaps/..` viraria `DELETE /v1/projects/:id`.
+ */
+export declare function hasDotSegment(path: string): boolean;
+/** Credencial de uma requisição: Bearer (rotas de usuário) ou a chave de projeto (rotas da chave). */
+export type RequestAuth = 'bearer' | 'key';
 export declare class TrackClient {
     readonly config: TrackClientConfig;
     constructor(config: TrackClientConfig);
     get baseUrl(): string;
     get hasToken(): boolean;
+    /** `FG_TRACKER_TOKEN` é um token pessoal `fgt_…` (não uma sessão). */
+    get hasAccessToken(): boolean;
+    get credentialKind(): CredentialKind;
+    /** Painel para links (`FG_TRACKER_WEB_URL` ou derivado da API); `null` se desconhecido. */
+    get webUrl(): string | null;
     get hasApiKey(): boolean;
-    /** Headers de autenticação: Bearer (sessão) e/ou chave de projeto. */
+    /**
+     * Headers de autenticação de uma requisição: o Bearer (token pessoal ou sessão) nas rotas de
+     * usuário, ou só a chave de projeto nas rotas da chave. Nunca os dois: a chave não viaja nas
+     * chamadas que o Bearer decide.
+     */
     private authHeaders;
-    request<T = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, options?: {
+    request<T = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, options?: {
         query?: Record<string, QueryValue>;
         body?: unknown;
         headers?: Record<string, string>;
+        onResponse?: (res: Response) => void;
+        auth?: RequestAuth;
+        timeoutMs?: number;
     }): Promise<T>;
+    private unauthorizedHint;
+    /** Dica de uma recusa 403 conforme o `code` e a permissão exigida que a API devolve. */
+    private forbiddenHint;
     get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<T>;
+    /**
+     * GET de uma leitura com janela: devolve também a janela absoluta que a API confirmou no
+     * cabeçalho `x-fg-tracker-window` (`null` = a API usou `range`, ou é anterior a from/to e os
+     * ignorou).
+     */
+    getWindowed<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<{
+        body: T;
+        window: {
+            from: string;
+            to: string;
+        } | null;
+        capabilities: Set<string>;
+    }>;
     post<T = unknown>(path: string, body?: unknown): Promise<T>;
     patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    /** POST numa rota da chave de projeto (`x-fg-tracker-key`), sem o Bearer. */
+    postWithKey<T = unknown>(path: string, body?: unknown): Promise<T>;
 }
 export type RangeKey = '15m' | '1h' | '6h' | '24h' | '7d' | '30d';
 export declare const RANGE_KEYS: readonly RangeKey[];

package/dist/client.js

@@ -1,8 +1,12 @@
 /**
  * Cliente HTTP mínimo para a API do FG Tracker (docs/CONTRATO.md §4, §8, §11).
- * Lê `FG_TRACKER_URL`, `FG_TRACKER_TOKEN` (Bearer de sessão), `FG_TRACKER_API_KEY`
- * (chave de projeto, header `x-fg-tracker-key`) e `FG_TRACKER_TIMEOUT_MS` — com
+ * Lê `FG_TRACKER_URL`, `FG_TRACKER_TOKEN` (Bearer: token pessoal `fgt_…` com as permissões
+ * marcadas no painel, ou token de sessão), `FG_TRACKER_API_KEY` (chave de projeto, header
+ * `x-fg-tracker-key`), `FG_TRACKER_TIMEOUT_MS` e `FG_TRACKER_WEB_URL` — com
  * fallback para os nomes legados `STREAD_TRACK_*` (`stread-track-mcp` ≤ 0.3).
+ *
+ * Cada requisição leva uma credencial só: o Bearer nas rotas de usuário (o padrão) e a chave
+ * apenas nas rotas da chave (`auth: 'key'`), que as ferramentas só usam sem FG_TRACKER_TOKEN.
  */
 /** API local do monorepo. Em produção a API é `https://tracker-api.fortground.com.br`. */
 export const DEFAULT_URL = 'http://localhost:4050';
@@ -19,11 +23,17 @@ export class TrackApiError extends Error {
     status;
     path;
     hint;
-    constructor(message, status, path, hint) {
+    code;
+    details;
+    constructor(message, status, path, hint, 
+    /** `code` do corpo de erro da API (ex.: TOKEN_SCOPE_INSUFFICIENT), quando houver. */
+    code, details = {}) {
         super(message);
         this.status = status;
         this.path = path;
         this.hint = hint;
+        this.code = code;
+        this.details = details;
         this.name = 'TrackApiError';
     }
     /** Mensagem amigável pronta para devolver ao agente. */
@@ -37,7 +47,27 @@ export function configFromEnv(env = process.env) {
     const apiKey = readEnv('API_KEY', env);
     const timeoutRaw = Number(readEnv('TIMEOUT_MS', env));
     const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 15_000;
-    return { baseUrl, token, apiKey, timeoutMs };
+    const webUrl = readEnv('WEB_URL', env)?.replace(/\/+$/, '');
+    return { baseUrl, token, apiKey, timeoutMs, ...(webUrl ? { webUrl } : {}) };
+}
+/**
+ * Painel que acompanha a API: `tracker-api.<domínio>` → `tracker.<domínio>` (o alias antigo
+ * `track-api` também), `localhost:4050` → `localhost:3050`. Sem regra conhecida, `null`:
+ * as ferramentas deixam de mandar links do painel, nunca inventam um.
+ */
+export function webUrlFor(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return null;
+    }
+    if (/^track(?:er)?-api\./.test(url.hostname))
+        return `${url.protocol}//${url.hostname.replace(/^track(?:er)?-api\./, 'tracker.')}`;
+    if ((url.hostname === 'localhost' || url.hostname === '127.0.0.1') && url.port === '4050')
+        return `${url.protocol}//${url.hostname}:3050`;
+    return null;
 }
 function buildQuery(query) {
     if (!query)
@@ -59,6 +89,47 @@ function isConnectionError(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return /fetch failed|ECONNREFUSED|network/i.test(msg);
 }
+/** Cabeçalho com a janela absoluta (`from`/`to`) que a API aplicou (CONTRATO.md §4). */
+export const WINDOW_HEADER = 'x-fg-tracker-window';
+/** Cabeçalho com os parâmetros extras que a rota aplicou (ex.: `traces-sort,traces-has-span`). */
+export const CAPABILITIES_HEADER = 'x-fg-tracker-capabilities';
+/** Prefixo dos tokens pessoais (CONTRATO.md §8.1). */
+export const ACCESS_TOKEN_PREFIX = 'fgt_';
+/**
+ * Esconde valores de credencial num texto que vai para o agente: chave de projeto `stk_…` e
+ * token pessoal `fgt_…`. As mensagens de erro da API não ecoam segredos; isto é a segunda linha.
+ */
+export function redactSecrets(value) {
+    return value.replace(/\b(stk|fgt)_[A-Za-z0-9_-]{6,}/g, '$1_…');
+}
+function extractCode(body) {
+    const code = body && typeof body === 'object' ? body.code : undefined;
+    return typeof code === 'string' ? code : undefined;
+}
+function extractDetails(body) {
+    if (!body || typeof body !== 'object')
+        return {};
+    const b = body;
+    const details = {};
+    if (typeof b.requiredScope === 'string' || b.requiredScope === null)
+        details.requiredScope = b.requiredScope;
+    if (typeof b.requiredPermission === 'string' || b.requiredPermission === null)
+        details.requiredPermission = b.requiredPermission;
+    if (typeof b.sessionOnly === 'boolean')
+        details.sessionOnly = b.sessionOnly;
+    if (typeof b.role === 'string')
+        details.role = b.role;
+    if (Array.isArray(b.requiredRoles))
+        details.requiredRoles = b.requiredRoles.map(String);
+    return details;
+}
+/**
+ * Segmento "." ou ".." (também `%2e`) num caminho: o `fetch` (WHATWG URL) o normaliza e a
+ * requisição vai para outra rota — `DELETE …/sourcemaps/..` viraria `DELETE /v1/projects/:id`.
+ */
+export function hasDotSegment(path) {
+    return path.split('?')[0].split('/').some((segment) => /^(?:\.|%2e){1,2}$/i.test(segment));
+}
 function extractMessage(body, fallback) {
     if (body && typeof body === 'object') {
         const m = body.message;
@@ -82,22 +153,44 @@ export class TrackClient {
     get hasToken() {
         return Boolean(this.config.token);
     }
+    /** `FG_TRACKER_TOKEN` é um token pessoal `fgt_…` (não uma sessão). */
+    get hasAccessToken() {
+        return Boolean(this.config.token?.startsWith(ACCESS_TOKEN_PREFIX));
+    }
+    get credentialKind() {
+        return this.hasAccessToken ? 'access_token' : this.config.token ? 'session' : 'none';
+    }
+    /** Painel para links (`FG_TRACKER_WEB_URL` ou derivado da API); `null` se desconhecido. */
+    get webUrl() {
+        return this.config.webUrl ?? webUrlFor(this.config.baseUrl);
+    }
     get hasApiKey() {
         return Boolean(this.config.apiKey);
     }
-    /** Headers de autenticação: Bearer (sessão) e/ou chave de projeto. */
-    authHeaders(extra) {
+    /**
+     * Headers de autenticação de uma requisição: o Bearer (token pessoal ou sessão) nas rotas de
+     * usuário, ou só a chave de projeto nas rotas da chave. Nunca os dois: a chave não viaja nas
+     * chamadas que o Bearer decide.
+     */
+    authHeaders(auth, extra) {
         const headers = { accept: 'application/json', ...extra };
-        if (this.config.token)
+        if (auth === 'key') {
+            if (this.config.apiKey)
+                headers[API_KEY_HEADER] = this.config.apiKey;
+        }
+        else if (this.config.token) {
             headers.authorization = `Bearer ${this.config.token}`;
-        if (this.config.apiKey)
-            headers[API_KEY_HEADER] = this.config.apiKey;
+        }
         return headers;
     }
     async request(method, path, options = {}) {
+        if (hasDotSegment(path)) {
+            throw new TrackApiError(`Recusado: ${method} ${path} tem um segmento "." ou "..", que mudaria a rota chamada. Nada foi enviado.`, undefined, path);
+        }
         const url = `${this.config.baseUrl}${path}${buildQuery(options.query)}`;
-        const headers = this.authHeaders(options.headers);
-        let init = { method, headers, signal: AbortSignal.timeout(this.config.timeoutMs ?? 15_000) };
+        const auth = options.auth ?? 'bearer';
+        const headers = this.authHeaders(auth, options.headers);
+        let init = { method, headers, signal: AbortSignal.timeout(options.timeoutMs ?? this.config.timeoutMs ?? 15_000) };
         if (options.body !== undefined) {
             headers['content-type'] = 'application/json';
             init = { ...init, body: JSON.stringify(options.body) };
@@ -126,33 +219,102 @@ export class TrackClient {
                 body = text;
             }
         }
-        if (res.ok)
+        if (res.ok) {
+            options.onResponse?.(res);
             return body;
-        const message = extractMessage(body, `${res.status} ${res.statusText}`);
+        }
+        const message = redactSecrets(extractMessage(body, `${res.status} ${res.statusText}`));
+        const code = extractCode(body);
+        const details = extractDetails(body);
+        const fail = (summary, hint) => {
+            throw new TrackApiError(summary, res.status, path, hint, code, details);
+        };
         switch (res.status) {
             case 401:
-                throw new TrackApiError(`Não autenticado (401) em ${method} ${path}: ${message}`, 401, path, this.config.token
-                    ? 'o FG_TRACKER_TOKEN expirou ou é inválido — faça login de novo (POST /v1/auth/login) e defina FG_TRACKER_TOKEN com o novo token.'
-                    : 'defina FG_TRACKER_TOKEN com um token de sessão do FG Tracker (POST /v1/auth/login → `token`). Para ingestão use FG_TRACKER_API_KEY.');
+                return fail(`Não autenticado (401) em ${method} ${path}: ${message}`, auth === 'key' ? 'a FG_TRACKER_API_KEY não é a chave de um projeto (stk_…): copie FG_TRACKER_KEY no painel, em Conectar.' : this.unauthorizedHint());
             case 403:
-                throw new TrackApiError(`Sem permissão (403) em ${method} ${path}: ${message}`, 403, path, 'o usuário do FG_TRACKER_TOKEN não é membro deste projeto. Peça a um owner/admin para convidá-lo em /members.');
+                return fail(`Sem permissão (403) em ${method} ${path}: ${message}`, this.forbiddenHint(method, path, code, details));
             case 404:
-                throw new TrackApiError(`Não encontrado (404) em ${method} ${path}: ${message}`, 404, path);
+                return fail(`Não encontrado (404) em ${method} ${path}: ${message}`);
             case 400:
-                throw new TrackApiError(`Requisição inválida (400) em ${method} ${path}: ${message}`, 400, path);
+                if (code === 'API_KEY_PROJECT_MISMATCH') {
+                    return fail(`Recusado (400) em ${method} ${path}: a FG_TRACKER_API_KEY é de outro projeto, não do projectId pedido. Nada foi gravado.`, 'sem FG_TRACKER_TOKEN, as ferramentas que gravam pela chave só valem no projeto dela: use o projectId da chave, troque FG_TRACKER_API_KEY pela chave do projeto certo ou configure FG_TRACKER_TOKEN.');
+                }
+                return fail(`Requisição inválida (400) em ${method} ${path}: ${message}`);
             default:
-                throw new TrackApiError(`Erro ${res.status} em ${method} ${path}: ${message}`, res.status, path);
+                return fail(`Erro ${res.status} em ${method} ${path}: ${message}`);
+        }
+    }
+    unauthorizedHint() {
+        if (this.hasAccessToken)
+            return 'o token pessoal do FG_TRACKER_TOKEN expirou, foi revogado ou a conta está inativa — crie outro no painel (Conta → Tokens de acesso), com as permissões de que o agente precisa, e atualize FG_TRACKER_TOKEN. A recusa é final: o MCP não tenta de novo com outra credencial.';
+        if (this.config.token)
+            return 'a sessão do FG_TRACKER_TOKEN expirou ou foi encerrada — crie um token pessoal no painel (Conta → Tokens de acesso), que não cai com logout, e defina FG_TRACKER_TOKEN com ele.';
+        return 'defina FG_TRACKER_TOKEN com um token pessoal do FG Tracker (painel → Conta → Tokens de acesso, `fgt_…`). Para ingestão use FG_TRACKER_API_KEY.';
+    }
+    /** Dica de uma recusa 403 conforme o `code` e a permissão exigida que a API devolve. */
+    forbiddenHint(method, path, code, details) {
+        switch (code) {
+            case 'TOKEN_SCOPE_INSUFFICIENT':
+                if (details.sessionOnly)
+                    return 'esta operação só pode ser feita com a sessão do painel: tokens pessoais não a fazem com nenhuma permissão. Peça ao usuário para fazê-la no painel.';
+                return details.requiredPermission
+                    ? `falta a permissão "${details.requiredPermission}" neste token. O usuário pode marcá-la em Conta → Tokens de acesso → editar; a lista de ferramentas do MCP só muda depois de reiniciar o cliente MCP.`
+                    : 'o token não tem a permissão que esta operação exige (Conta → Tokens de acesso → editar; reinicie o cliente MCP depois).';
+            case 'PROJECT_ROLE_INSUFFICIENT':
+                return `seu papel neste projeto é ${details.role ?? 'outro'}${details.requiredRoles?.length ? `, e a ação exige ${details.requiredRoles.join(' ou ')}` : ''}. Nenhum token faz mais do que o papel: peça a um owner ou admin do projeto.`;
+            case 'TOKEN_PROJECT_SCOPE':
+                return method === 'POST' && path === '/v1/projects'
+                    ? 'um token restrito a projetos não cria projeto. Use um token válido para todos os projetos (com "Projetos: criar e editar") ou a sessão do painel.'
+                    : 'o token não vale para este projeto: ele foi restrito a outros projetos (Conta → Tokens de acesso → projetos do token).';
+            case 'PROJECT_ACCESS_DENIED':
+                return 'o usuário da credencial não é membro ativo deste projeto. Peça a um owner/admin para convidá-lo.';
+            case 'EMAIL_VERIFICATION_REQUIRED':
+                return 'confirme o e-mail da conta no painel antes de continuar.';
+            default:
+                return this.hasAccessToken
+                    ? 'o usuário do token não tem acesso a este projeto ou o token não cobre esta operação (Conta → Tokens de acesso).'
+                    : 'o usuário do FG_TRACKER_TOKEN não tem acesso a este projeto ou a esta operação. Peça a um owner/admin.';
         }
     }
     get(path, query) {
         return this.request('GET', path, { query });
     }
+    /**
+     * GET de uma leitura com janela: devolve também a janela absoluta que a API confirmou no
+     * cabeçalho `x-fg-tracker-window` (`null` = a API usou `range`, ou é anterior a from/to e os
+     * ignorou).
+     */
+    async getWindowed(path, query) {
+        let window = null;
+        let capabilities = new Set();
+        const body = await this.request('GET', path, {
+            query,
+            onResponse: (res) => {
+                const [from, to] = (res.headers.get(WINDOW_HEADER) ?? '').split('/');
+                if (from && to)
+                    window = { from, to };
+                capabilities = new Set((res.headers.get(CAPABILITIES_HEADER) ?? '').split(',').map((item) => item.trim()).filter(Boolean));
+            },
+        });
+        return { body, window, capabilities };
+    }
     post(path, body) {
         return this.request('POST', path, { body });
     }
     patch(path, body) {
         return this.request('PATCH', path, { body });
     }
+    put(path, body) {
+        return this.request('PUT', path, { body });
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+    /** POST numa rota da chave de projeto (`x-fg-tracker-key`), sem o Bearer. */
+    postWithKey(path, body) {
+        return this.request('POST', path, { body, auth: 'key' });
+    }
 }
 export const RANGE_KEYS = ['15m', '1h', '6h', '24h', '7d', '30d'];
 export const RANGE_SECONDS = {