fg-tracker-mcp 0.9.1 → 0.10.0

package/dist/server.js

@@ -1,37 +1,149 @@
 import { detectDatabases, databaseGuide } from "./database.js";
 /**
- * Servidor MCP do FG Track (docs/CONTRATO.md §12): tools, prompt e resource.
+ * Servidor MCP do FG Tracker (docs/CONTRATO.md §12): tools, prompt e resource.
  * O transporte (stdio) é conectado em `cli.ts`.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { RANGE_KEYS, RANGE_SECONDS, TrackApiError, TrackClient, configFromEnv, } from './client.js';
+import { RANGE_KEYS, RANGE_SECONDS, TrackApiError, TrackClient, configFromEnv, readEnv, } from './client.js';
 import { LEGACY_QUICKSTART_URI, QUICKSTART_URI, instrumentProjectPrompt, quickstartMarkdown } from './docs.js';
-import { ago, compact, guard, json, ms, pct, text } from './format.js';
+import { MAX_ITEMS_CEILING, MAX_TRACE_SPANS, ago, cappedNote, clampLimit, compact, guard, json, listPage, maxItemsFromEnv, ms, pct, preview, text, truncateList, until, } from './format.js';
 import { FRAMEWORKS, buildGuide } from './guide.js';
 import { registerInfraTools } from './infra/tools.js';
 import { registerLoadtestTools } from './loadtest/tools.js';
 export const SERVER_NAME = 'fg-tracker';
-export const SERVER_VERSION = '0.9.0';
+export const SERVER_VERSION = '0.10.0';
 const rangeSchema = z.enum(RANGE_KEYS).default('24h').describe('Janela: 15m|1h|6h|24h|7d|30d (default 24h)');
-const projectIdSchema = z.string().uuid().describe('ID (uuid) do projeto — veja track_list_projects');
+const projectIdSchema = z.string().uuid().describe('ID (uuid) do projeto — veja tracker_list_projects');
+const rootKindSchema = z
+    .enum(['http', 'custom', 'all'])
+    .optional()
+    .describe('Tipo da raiz: http = requisições (default), custom = jobs/tarefas (tracker.span("custom", ...) sem pai), all = qualquer raiz');
+const serviceFilterSchema = z.string().min(1).max(120).optional().describe('Só execuções deste serviço (serviceName da raiz, igualdade exata; valores em `services` de tracker_get_overview)');
+const envFilterSchema = z.string().min(1).max(64).optional().describe('Só execuções deste ambiente (environment da raiz, igualdade exata; valores em `environments` de tracker_get_overview)');
+/** Descreve os filtros de raiz aplicados, para as mensagens de resumo. */
+function filterNote(filters) {
+    const parts = [
+        filters.rootKind && filters.rootKind !== 'http' ? `rootKind ${filters.rootKind}` : '',
+        filters.service ? `service ${filters.service}` : '',
+        filters.env ? `env ${filters.env}` : '',
+    ].filter(Boolean);
+    return parts.length ? ` (${parts.join(', ')})` : '';
+}
+/** Valores para o resumo em texto com o mesmo corte do JSON (`compact`), avisando quantos ficaram de fora. */
+function joinCapped(values) {
+    if (!values?.length)
+        return '—';
+    const { items, truncated } = truncateList(values);
+    return `${items.join(', ')}${truncated > 0 ? ` (+${truncated} omitidos)` : ''}`;
+}
 const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
+const ISSUE_TYPES = ['N_PLUS_ONE', 'LOOP', 'SLOW_ENDPOINT', 'UNTRACED_GAP', 'ERROR'];
+const ISSUE_SEVERITIES = ['low', 'medium', 'high', 'critical'];
+const ISSUE_SORTS = ['recent', 'impact', 'count', 'first'];
+/** `high · última medium (55%)`: a máxima histórica e, quando houver, a última detecção. */
+function severityLabel(issue) {
+    const metric = issue.lastMetric;
+    const measure = !metric
+        ? ''
+        : metric.unit === 'ratio'
+            ? `${Math.round(metric.value * 100)}%`
+            : metric.unit === 'ms'
+                ? ms(metric.value)
+                : `×${metric.value}`;
+    if (issue.lastSeverity && issue.lastSeverity !== issue.severity)
+        return `${issue.severity} · última ${issue.lastSeverity}${measure ? ` (${measure})` : ''}`;
+    return measure ? `${issue.severity} (última ${measure})` : issue.severity;
+}
 function rangeWindow(range, now = Date.now()) {
     return { from: new Date(now - RANGE_SECONDS[range] * 1000).toISOString(), to: new Date(now).toISOString() };
 }
+/** Prefixo das ferramentas próprias do FG Tracker (`infra_*` e `loadtest_*` têm o seu). */
+export const TOOL_PREFIX = 'tracker_';
+/**
+ * @deprecated prefixo até a 0.9 (`track_status`, `track_list_projects`…). Os nomes antigos seguem
+ * registrados como aliases, para clientes com permissões ou prompts salvos com eles; saem na 1.0.
+ */
+export const LEGACY_TOOL_PREFIX = 'track_';
+export function legacyToolNamesFromEnv(env = process.env) {
+    const value = readEnv('LEGACY_TOOL_NAMES', env)?.toLowerCase();
+    return !(value === '0' || value === 'false' || value === 'off');
+}
+/** Cada `tracker_x` registrado ganha o alias `track_x`, com o mesmo schema e handler. */
+function registerLegacyToolAliases(server) {
+    const register = server.registerTool.bind(server);
+    server.registerTool = (name, config, handler) => {
+        const tool = register(name, config, handler);
+        if (name.startsWith(TOOL_PREFIX)) {
+            const legacy = LEGACY_TOOL_PREFIX + name.slice(TOOL_PREFIX.length);
+            // Descrição curta: o alias só existe para quem já chama o nome antigo, e repetir a descrição
+            // inteira aumentaria em cerca de metade o tools/list de todo cliente.
+            register(legacy, {
+                ...config,
+                title: config.title ? `${config.title} (nome obsoleto)` : undefined,
+                description: `Nome obsoleto: use ${name} (${legacy} sai na 1.0). Mesmos parâmetros e mesmo resultado.`,
+            }, handler);
+        }
+        return tool;
+    };
+}
+/** Validade da credencial de FG_TRACKER_TOKEN (GET /v1/auth/me), sem mostrar o token. */
+async function describeCredential(client, now = Date.now()) {
+    let me;
+    try {
+        me = await client.get('/v1/auth/me');
+    }
+    catch (err) {
+        if (err instanceof TrackApiError && err.status === 404)
+            return 'Validade do token: desconhecida (esta API não expõe GET /v1/auth/me).';
+        return `Validade do token: ${err instanceof TrackApiError ? err.describe() : String(err)}`;
+    }
+    const credential = me.credential ?? null;
+    const isToken = credential?.type === 'token';
+    let label = me.session || credential?.type === 'session' ? 'sessão' : 'credencial';
+    if (isToken) {
+        const projects = credential.projectIds === null ? 'todos os projetos' : Array.isArray(credential.projectIds) ? `${credential.projectIds.length} projeto(s)` : '';
+        const scope = [credential.scope ? `escopo ${credential.scope}` : '', projects].filter(Boolean).join(', ');
+        label = `token pessoal${credential.name ? ` "${credential.name}"` : ''}${scope ? ` (${scope})` : ''}`;
+    }
+    const renewal = isToken ? '' : ' Cada uso na segunda metade da validade renova a sessão; logout e troca de senha a revogam.';
+    const expiresAt = credential?.expiresAt ?? me.session?.expiresAt ?? null;
+    if (!expiresAt)
+        return `Validade do token: ${label}, sem data de expiração.`;
+    const t = Date.parse(expiresAt);
+    if (Number.isNaN(t))
+        return `Validade do token: ${label}, expira em ${expiresAt}.`;
+    if (t <= now)
+        return `Validade do token: ${label} expirou ${ago(expiresAt, now)} (${expiresAt}). Gere um novo e atualize FG_TRACKER_TOKEN.`;
+    const soon = t - now < 2 * 86_400_000 ? ' ATENÇÃO: perto de expirar; gere um novo e atualize FG_TRACKER_TOKEN.' : '';
+    return `Validade do token: ${label}, expira ${until(expiresAt, now)} (${expiresAt}).${soon}${renewal}`;
+}
+function monitorLabel(m) {
+    const env = 'environment' in m ? ` · ${m.environment ?? 'sem ambiente'}` : '';
+    return `[${m.status}] ${m.name} (${m.kind}, ${m.slug}${env})`;
+}
+/** Execução mais recente que reportou trace (`recent` vem do mais antigo para o mais novo). */
+function lastTraced(recent) {
+    return [...(recent ?? [])].reverse().find((check) => check.traceId);
+}
 export function createServer(options = {}) {
     const client = options.client ?? new TrackClient(configFromEnv());
+    const outputLimit = maxItemsFromEnv();
+    const maxItems = outputLimit.value;
+    const legacyToolNames = options.legacyToolNames ?? legacyToolNamesFromEnv();
     const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
         instructions: [
-            'Servidor MCP do FG Track (APM para Node: traces distribuídos, queries de qualquer banco via adapters, provedores externos, logs, issues com impacto por usuário e commits suspeitos, releases, monitores de uptime/jobs, detecção de N+1/loops/lentidão/erros).',
-            `API: ${client.baseUrl}. Comece por track_status; depois track_list_projects para obter projectId.`,
-            'Para conectar um app use o prompt instrument-project ou track_detect_databases + track_instrumentation_guide + track_verify_ingest.',
+            'Servidor MCP do FG Tracker (APM para Node: traces distribuídos, queries de qualquer banco via adapters, provedores externos, logs, issues com impacto por usuário e commits suspeitos, releases, monitores de uptime/jobs, detecção de N+1/loops/lentidão/erros).',
+            `API: ${client.baseUrl}. Comece por tracker_status; depois tracker_list_projects para obter projectId.`,
+            'Para conectar um app use o prompt instrument-project ou tracker_detect_databases + tracker_instrumentation_guide + tracker_verify_ingest.',
             'Ranges aceitos: 15m|1h|6h|24h|7d|30d.',
-            'Infraestrutura AWS: prompt connect-infrastructure ou tools infra_* (nenhuma altera recursos na AWS; mudanças só com aprovação humana no FG Track).',
+            'Infraestrutura AWS: prompt connect-infrastructure ou tools infra_* (nenhuma altera recursos na AWS; mudanças só com aprovação humana no FG Tracker).',
             'Testes de carga (Simular ambiente): prompt create-load-test ou tools loadtest_* (loadtest_start_run só com confirmação explícita do usuário).',
         ].join(' '),
     });
-    server.registerTool('track_detect_databases', {
+    if (legacyToolNames)
+        registerLegacyToolAliases(server);
+    server.registerTool('tracker_detect_databases', {
         title: 'Identify database drivers in the local project',
         description: 'Inspect local manifests/imports without reading secrets. Returns all candidate drivers, initialization files and the correct SDK integration guide. The coding agent must apply the guide to the active clients and verify request-linked db.query spans.',
         inputSchema: { projectPath: z.string().min(1).describe('Absolute path of the application authorized for instrumentation'), serviceName: z.string().default('app') },
@@ -42,9 +154,9 @@ export function createServer(options = {}) {
             (detected.databases.length ? detected.databases.map(x => databaseGuide(x.package, serviceName)).join('\n\n') : databaseGuide('generic', serviceName)));
     }));
     /* ---------------- tools ---------------- */
-    server.registerTool('track_status', {
-        title: 'Status do FG Track',
-        description: 'Verifica se a API do FG Track está no ar (GET /v1/health), qual URL/credenciais este servidor está usando e quantos projetos o token enxerga. Comece por aqui.',
+    server.registerTool('tracker_status', {
+        title: 'Status do FG Tracker',
+        description: 'Verifica se a API do FG Tracker está no ar (GET /v1/health), qual URL/credenciais este servidor está usando e quantos projetos o token enxerga. Comece por aqui.',
         inputSchema: {},
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async () => guard(async () => {
@@ -53,7 +165,10 @@ export function createServer(options = {}) {
             `API: ${client.baseUrl} — ${health.status} (versão ${health.version}, banco ${health.database}, uptime ${Math.round(health.uptimeSeconds)} s)`,
             `FG_TRACKER_TOKEN: ${client.hasToken ? 'definido' : 'ausente (necessário quando a API exige login: projetos/métricas/logs)'}`,
             `FG_TRACKER_API_KEY: ${client.hasApiKey ? 'definido' : 'ausente (opcional; só para ingestão)'}`,
+            `Itens por lista (FG_TRACKER_MAX_ITEMS): até ${maxItems}${outputLimit.warning ? ` — ${outputLimit.warning}` : ''}`,
         ];
+        if (client.hasToken)
+            lines.push(await describeCredential(client));
         try {
             const projects = await client.get('/v1/projects');
             lines.push(`Projetos acessíveis: ${projects.length}${projects.length ? ' — ' + projects.map((p) => `${p.name} (${p.id})`).slice(0, 10).join(', ') : ''}`);
@@ -70,7 +185,7 @@ export function createServer(options = {}) {
         }
         return text(lines.join('\n'));
     }));
-    server.registerTool('track_list_projects', {
+    server.registerTool('tracker_list_projects', {
         title: 'Listar projetos',
         description: 'Lista os projetos que o usuário do token enxerga, com apiKey, limiares, domínios permitidos (allowedOrigins: CORS do SDK de navegador) e estatísticas de 24h (requests, taxa de erro, p95, issues abertas).',
         inputSchema: {},
@@ -78,8 +193,10 @@ export function createServer(options = {}) {
     }, async () => guard(async () => {
         const projects = await client.get('/v1/projects');
         if (projects.length === 0)
-            return text('Nenhum projeto. Crie um com track_create_project { name }.');
+            return text('Nenhum projeto. Crie um com tracker_create_project { name }.');
+        const page = listPage(projects, maxItems);
         const summary = projects
+            .slice(0, maxItems)
             .map((p) => {
             const s = p.stats;
             const stats = s ? ` · 24h: ${s.requests24h} req, erro ${pct(s.errorRate24h)}, p95 ${ms(s.p95Ms24h)}, ${s.openIssues} issues` : '';
@@ -87,21 +204,22 @@ export function createServer(options = {}) {
             return `- ${p.name} — id ${p.id} · slug ${p.slug} · apiKey ${p.apiKey}${stats}${origins}`;
         })
             .join('\n');
-        return json(compact(projects), summary);
+        const more = page.truncated ? `\nMostrando ${page.returned} de ${page.total} projetos (FG_TRACKER_MAX_ITEMS=${maxItems}).` : '';
+        return json(page, summary + more);
     }));
-    server.registerTool('track_create_project', {
+    server.registerTool('tracker_create_project', {
         title: 'Criar projeto',
-        description: 'Cria um projeto no FG Track e devolve o projeto com a apiKey (stk_...) para colocar em FG_TRACKER_KEY do app instrumentado.',
+        description: 'Cria um projeto no FG Tracker e devolve o projeto com a apiKey (stk_...) para colocar em FG_TRACKER_KEY do app instrumentado.',
         inputSchema: { name: z.string().min(1).max(120).describe('Nome do projeto (ex.: "minha-api")') },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, async ({ name }) => guard(async () => {
         const project = await client.post('/v1/projects', { name });
-        return json(project, `Projeto "${project.name}" criado.\n- projectId: ${project.id}\n- apiKey: ${project.apiKey}\n\nPróximo passo: track_instrumentation_guide { framework, projectId: "${project.id}" }.`);
+        return json(project, `Projeto "${project.name}" criado.\n- projectId: ${project.id}\n- apiKey: ${project.apiKey}\n\nPróximo passo: tracker_instrumentation_guide { framework, projectId: "${project.id}" }.`);
     }));
-    server.registerTool('track_update_allowed_origins', {
+    server.registerTool('tracker_update_allowed_origins', {
         title: 'Definir domínios permitidos do projeto',
         description: 'SUBSTITUI a lista de domínios permitidos (allowedOrigins) do projeto: origens de navegador que podem enviar pageviews/traces pelo SDK de navegador (CORS de POST /v1/ingest). ' +
-            'Antes de chamar, leia a lista atual com track_list_projects, monte a lista completa (atual + novas − removidas) e confirme com o usuário — origens omitidas deixam de ser aceitas. ' +
+            'Antes de chamar, leia a lista atual com tracker_list_projects, monte a lista completa (atual + novas − removidas) e confirme com o usuário — origens omitidas deixam de ser aceitas. ' +
             'Cada origem é `scheme://host[:porta]` sem caminho: https:// para qualquer host, http:// só localhost/127.0.0.1, curinga de subdomínio `https://*.dominio.com` (não inclui o domínio raiz), máx. 100. Lista vazia remove todas. Requer owner/admin. ' +
             'Pode levar até 30 s para valer em todas as instâncias da API.',
         inputSchema: {
@@ -114,129 +232,229 @@ export function createServer(options = {}) {
         const saved = project.allowedOrigins ?? [];
         return json({ id: project.id, name: project.name, allowedOrigins: saved }, `Domínios permitidos de "${project.name}" (${saved.length}):${saved.length ? '\n' + saved.map((origin) => `- ${origin}`).join('\n') : ' nenhum (só TRACK_INGEST_ORIGINS da API vale)'}`);
     }));
-    server.registerTool('track_get_overview', {
+    server.registerTool('tracker_get_overview', {
         title: 'Visão geral do projeto',
-        description: 'Métricas agregadas do projeto no range: requests, taxa de erro, p50/p95/p99, apdex, throughput, issues abertas, breakdown por status, top endpoints lentos e com erro, e série temporal (amostrada).',
-        inputSchema: { projectId: projectIdSchema, range: rangeSchema },
+        description: 'Métricas agregadas do projeto no range: requests HTTP, taxa de erro, p50/p95/p99, apdex, throughput, issues abertas, breakdown por status, top endpoints lentos e com erro e série temporal (amostrada). ' +
+            'Jobs (raízes custom) vêm à parte em `jobs` (execuções, erros, p50/p95 e última rodada) e não entram em requests/apdex/status. ' +
+            '`services`/`environments` listam os valores vistos no range para usar em service/env; os filtros valem para HTTP e jobs, issues abertas são do projeto inteiro.',
+        inputSchema: { projectId: projectIdSchema, range: rangeSchema, service: serviceFilterSchema, env: envFilterSchema },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId, range }) => guard(async () => {
-        const overview = await client.get(`/v1/projects/${projectId}/overview`, { range });
+    }, async ({ projectId, range, service, env }) => guard(async () => {
+        const overview = await client.get(`/v1/projects/${projectId}/overview`, { range, service, env });
         const o = overview;
-        const summary = `Range ${range}: ${o.requests ?? 0} requests · erro ${pct(o.errorRate)} · p50 ${ms(o.p50Ms)} · p95 ${ms(o.p95Ms)} · p99 ${ms(o.p99Ms)} · apdex ${o.apdex ?? '—'} · ${o.openIssues ?? 0} issues abertas`;
-        return json(compact(overview), summary);
+        const lines = [
+            `Range ${range}${filterNote({ service, env })}: ${o.requests ?? 0} requests · erro ${pct(o.errorRate)} · p50 ${ms(o.p50Ms)} · p95 ${ms(o.p95Ms)} · p99 ${ms(o.p99Ms)} · apdex ${o.apdex ?? '—'} · ${o.openIssues ?? 0} issues abertas`,
+        ];
+        if (o.jobs) {
+            lines.push(o.jobs.executions === 0
+                ? 'Jobs (raízes custom): nenhuma execução no range.'
+                : `Jobs (raízes custom): ${o.jobs.executions} execuções de ${o.jobs.names} jobs · erro ${pct(o.jobs.errorRate)} · última ${o.jobs.lastRunAt ? ago(o.jobs.lastRunAt) : '—'}`, ...o.jobs.items.map((j) => `- ${j.name}: ${j.executions}× · erro ${pct(j.errorRate)} · p50 ${ms(j.p50Ms)} · p95 ${ms(j.p95Ms)} · última ${ago(j.lastRunAt)}`));
+            if (o.jobs.names > o.jobs.items.length)
+                lines.push(`(+${o.jobs.names - o.jobs.items.length} jobs: tracker_list_endpoints { rootKind: "custom" })`);
+        }
+        if (o.services?.length || o.environments?.length) {
+            lines.push(`Serviços: ${joinCapped(o.services)} · Ambientes: ${joinCapped(o.environments)}`);
+        }
+        return json(compact(overview), lines.join('\n'));
     }));
-    server.registerTool('track_list_endpoints', {
+    server.registerTool('tracker_list_endpoints', {
         title: 'Listar endpoints',
-        description: 'Endpoints do projeto no range com requests, taxa de erro, p50/p95/p99, média, último acesso, sparkline de p95 e nº de issues. Ordenável e filtrável por texto.',
+        description: 'Endpoints do projeto no range com requests, erros, taxa de erro, p50/p95/p99, média, último acesso (lastSeen), sparkline de p95 e nº de issues. Ordenável e filtrável por texto. ' +
+            'rootKind: "custom" lista jobs/tarefas (requests = execuções, lastSeen = última rodada; spans filhos não contam), "all" mistura (campo kind). Filtros service/env valem para a raiz.',
         inputSchema: {
             projectId: projectIdSchema,
             range: rangeSchema,
+            rootKind: rootKindSchema,
+            service: serviceFilterSchema,
+            env: envFilterSchema,
             search: z.string().optional().describe('Filtro textual no nome (ex.: "/users")'),
             sort: z.enum(['p95', 'requests', 'errorRate', 'name']).optional().describe('Ordenação (default p95)'),
-            limit: z.number().int().min(1).max(100).optional().describe('Máximo de itens devolvidos (default 25)'),
+            limit: z.number().int().min(1).max(MAX_ITEMS_CEILING).optional().describe('Máximo de itens devolvidos (default 25; até FG_TRACKER_MAX_ITEMS)'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId, range, search, sort, limit }) => guard(async () => {
-        const endpoints = await client.get(`/v1/projects/${projectId}/endpoints`, { range, search, sort });
-        const max = limit ?? 25;
+    }, async ({ projectId, range, rootKind, service, env, search, sort, limit }) => guard(async () => {
+        const endpoints = await client.get(`/v1/projects/${projectId}/endpoints`, { range, rootKind, service, env, search, sort });
+        const requested = limit ?? 25;
+        const max = clampLimit(requested, maxItems).limit;
         const shown = endpoints.slice(0, max);
-        const summary = `${endpoints.length} endpoints no range ${range}${endpoints.length > max ? ` (mostrando ${max})` : ''}.`;
+        const noun = rootKind === 'custom' ? 'jobs' : rootKind === 'all' ? 'raízes' : 'endpoints';
+        const summary = `${endpoints.length} ${noun} no range ${range}${filterNote({ rootKind, service, env })}${endpoints.length > max ? ` (mostrando ${max})` : ''}.${cappedNote(requested, max)}`;
         return json(shown, summary + (endpoints.length > max ? ` Use limit/search para ver o restante.` : ''));
     }));
-    server.registerTool('track_list_issues', {
+    server.registerTool('tracker_list_issues', {
         title: 'Listar issues',
-        description: 'Issues detectadas automaticamente (N_PLUS_ONE, LOOP, SLOW_ENDPOINT, UNTRACED_GAP, ERROR) com severidade, contagem, primeira/última ocorrência, trace de amostra e detalhes.',
+        description: 'Issues detectadas automaticamente (N_PLUS_ONE, LOOP, SLOW_ENDPOINT, UNTRACED_GAP, ERROR), paginadas, com filtros por status, tipo, severidade, texto no título/fingerprint e release. `severity` é a maior já detectada; `lastSeverity` e `lastMetric` descrevem a última detecção (null = desconhecida, issue sem detecção recente registrada). Para ver mais, repita a chamada com o `nextCursor` devolvido.',
         inputSchema: {
             projectId: projectIdSchema,
             status: z.enum(['open', 'resolved', 'ignored', 'all']).default('open').describe('Filtro de status (default open)'),
+            sort: z
+                .enum(ISSUE_SORTS)
+                .default('recent')
+                .describe('recent = última ocorrência · impact = escalando, usuários afetados e ocorrências em 24h · count = mais ocorrências · first = mais novas'),
+            type: z.array(z.enum(ISSUE_TYPES)).min(1).max(ISSUE_TYPES.length).optional().describe('Um ou mais tipos'),
+            severity: z.array(z.enum(ISSUE_SEVERITIES)).min(1).max(ISSUE_SEVERITIES.length).optional().describe('Severidade máxima histórica'),
+            q: z.string().trim().min(1).max(200).optional().describe('Texto no título ou na fingerprint, ex.: "media job"'),
+            release: z.string().min(1).max(200).optional().describe('Issues vistas nesta release'),
+            limit: z.number().int().min(1).max(200).default(50).describe('Itens por página (até 200)'),
+            cursor: z.string().max(512).optional().describe('nextCursor da página anterior; use os mesmos filtros e sort'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId, status }) => guard(async () => {
-        const issues = await client.get(`/v1/projects/${projectId}/issues`, { status });
-        if (issues.length === 0)
-            return text(`Nenhuma issue com status "${status}".`);
-        const summary = issues
-            .slice(0, 25)
-            .map((i) => `- [${i.severity}] ${i.type}: ${i.title} (×${i.count}${i.sampleTraceId ? `, trace ${i.sampleTraceId}` : ''})`)
-            .join('\n');
-        return json(compact(issues), `${issues.length} issues (${status}):\n${summary}`);
+    }, async ({ projectId, status, sort, type, severity, q, release, limit, cursor }) => guard(async () => {
+        const size = clampLimit(limit, maxItems);
+        const res = await client.get(`/v1/projects/${projectId}/issues`, {
+            status,
+            sort,
+            type: type?.join(','),
+            severity: severity?.join(','),
+            q,
+            release,
+            limit: size.limit,
+            cursor,
+        });
+        // API anterior à paginação: devolve array com tudo e ignora os filtros novos.
+        const legacy = Array.isArray(res);
+        const page = legacy ? { items: res.slice(0, size.limit), nextCursor: null, total: res.length, counts: null, limit: size.limit } : res;
+        const filters = [type?.length ? `tipo ${type.join('|')}` : '', severity?.length ? `severidade ${severity.join('|')}` : '', q ? `"${q}"` : '', release ? `release ${release}` : '']
+            .filter(Boolean)
+            .join(', ');
+        const byStatus = page.counts ? `Por status com esses filtros: ${page.counts.open} abertas · ${page.counts.resolved} resolvidas · ${page.counts.ignored} ignoradas` : '';
+        if (page.items.length === 0) {
+            return text(`Nenhuma issue com status "${status}"${filters ? ` (${filters})` : ''}${cursor ? ' nesta página' : ''}.${byStatus ? `\n${byStatus}` : ''}`);
+        }
+        const header = [
+            `${page.total} issues (${status}${filters ? `; ${filters}` : ''}; sort ${sort}) · mostrando ${page.items.length}${page.nextCursor ? ' · há mais: repita com cursor = nextCursor' : ''}${cappedNote(limit, size.limit)}`,
+            byStatus,
+            legacy && (type || severity || q || release || cursor) ? 'Aviso: esta API ainda não pagina nem filtra issues; os filtros e o cursor foram ignorados.' : '',
+            legacy && page.total > page.items.length ? `A API não devolve cursor: aumente limit (até 200) para ver mais.` : '',
+        ].filter(Boolean);
+        const lines = page.items.map((i) => `- [${severityLabel(i)}] ${i.type}: ${i.title} (×${i.count}${i.sampleTraceId ? `, trace ${i.sampleTraceId}` : ''}) · id ${i.id}`);
+        return json({ ...page, items: page.items.map((i) => compact(i)) }, `${header.join('\n')}\n${lines.join('\n')}`);
     }));
-    server.registerTool('track_list_traces', {
+    server.registerTool('tracker_list_traces', {
         title: 'Listar traces',
-        description: 'Traces recentes do projeto (para escolher um traceId e chamar track_get_trace). Filtros: endpoint, status ok|error, duração mínima.',
+        description: 'Traces recentes do projeto (para escolher um traceId e chamar tracker_get_trace), um item por trace. Filtros: endpoint, status ok|error, duração mínima, release, userId, rootKind (custom = jobs), service e env, todos aplicados à raiz; ' +
+            'num trace distribuído a raiz mais antiga que casa com os filtros representa o trace. Paginado pela API: repita com cursor = nextCursor.',
         inputSchema: {
             projectId: projectIdSchema,
             range: rangeSchema,
-            endpoint: z.string().optional().describe('Nome do endpoint (ex.: "GET /users/:id")'),
+            rootKind: rootKindSchema,
+            service: serviceFilterSchema,
+            env: envFilterSchema,
+            endpoint: z.string().optional().describe('Nome do endpoint ou job (ex.: "GET /users/:id", "media job")'),
             status: z.enum(['ok', 'error']).optional(),
             minDurationMs: z.number().min(0).optional(),
-            limit: z.number().int().min(1).max(200).default(20),
+            limit: z.number().int().min(1).max(200).default(20).describe('Traces por página (default 20, máx. 200; até FG_TRACKER_MAX_ITEMS)'),
             cursor: z.string().optional().describe('nextCursor da página anterior'),
+            release: z.string().max(200).optional().describe('Só traces desta release (attributes.release)'),
+            userId: z.string().max(200).optional().describe('Só traces deste usuário (attributes.user.id)'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId, range, endpoint, status, minDurationMs, limit, cursor }) => guard(async () => {
-        const res = await client.get(`/v1/projects/${projectId}/traces`, { range, endpoint, status, minDurationMs, limit, cursor });
+    }, async ({ projectId, range, rootKind, service, env, endpoint, status, minDurationMs, limit, cursor, release, userId }) => guard(async () => {
+        const page = clampLimit(limit, maxItems);
+        const res = await client.get(`/v1/projects/${projectId}/traces`, { range, rootKind, service, env, endpoint, status, minDurationMs, limit: page.limit, cursor, release, userId });
         if (res.items.length === 0)
-            return text(`Nenhum trace no range ${range}${endpoint ? ` para ${endpoint}` : ''}.`);
-        const lines = res.items.map((t) => `- ${t.traceId} · ${t.name} · ${t.statusCode ?? '—'} · ${ms(t.durationMs)} · ${t.spanCount} spans/${t.dbQueries} queries · ${ago(t.startedAt)}${t.hasIssue ? ' · ISSUE' : ''}`);
-        return json(res, `${res.items.length} traces${res.nextCursor ? ' (há mais: use cursor)' : ''}:\n${lines.join('\n')}`);
+            return text(`Nenhum trace no range ${range}${endpoint ? ` para ${endpoint}` : ''}${release ? ` na release ${release}` : ''}${userId ? ` do usuário ${userId}` : ''}${filterNote({ rootKind, service, env })}.`);
+        const lines = res.items.map((t) => `- ${t.traceId} · ${t.name}${t.kind && t.kind !== 'http.server' ? ` [${t.kind}]` : ''}${t.service ? ` · ${t.service}` : ''} · ${t.statusCode ?? '—'} · ${ms(t.durationMs)} · ${t.spanCount} spans/${t.dbQueries} queries · ${ago(t.startedAt)}${t.hasIssue ? ' · ISSUE' : ''}`);
+        return json(res, `${res.items.length} traces${res.nextCursor ? ' (há mais: use cursor)' : ''}:${cappedNote(limit, page.limit)}\n${lines.join('\n')}`);
     }));
-    server.registerTool('track_get_trace', {
+    server.registerTool('tracker_get_trace', {
         title: 'Detalhe de um trace',
-        description: 'Waterfall de um trace: spans em pré-ordem com depth/offsetMs, issues ligadas, resumo por kind, spans repetidos (evidência de N+1/loop) e `gaps` — trechos do request que nenhum span explica. Limitado a 80 spans.',
-        inputSchema: { projectId: projectIdSchema, traceId: z.string().min(1).describe('traceId (veja track_list_traces ou sampleTraceId de uma issue)') },
+        description: 'Waterfall de um trace: spans em pré-ordem com depth/offsetMs, issues ligadas, resumo por kind, spans repetidos (evidência de N+1/loop) e `gaps` — trechos do request que nenhum span explica. ' +
+            'Spans paginados: até 80 por página (spanLimit, até FG_TRACKER_MAX_ITEMS); `spanPage` traz total, quantos casaram com os filtros e nextSpanOffset para a próxima página. Filtros: kind, service, name (contém). ' +
+            'A API devolve o trace inteiro; a paginação é feita pelo MCP sobre essa resposta (spans que chegarem depois mudam as posições).',
+        inputSchema: {
+            projectId: projectIdSchema,
+            traceId: z.string().min(1).describe('traceId (veja tracker_list_traces ou sampleTraceId de uma issue)'),
+            spanOffset: z.number().int().min(0).default(0).describe('Posição do primeiro span na lista (pré-ordem, depois dos filtros); use nextSpanOffset'),
+            spanLimit: z.number().int().min(1).max(MAX_ITEMS_CEILING).default(MAX_TRACE_SPANS).describe(`Spans por página (default ${MAX_TRACE_SPANS}; até FG_TRACKER_MAX_ITEMS)`),
+            kind: z.string().max(64).optional().describe('Só spans deste kind (ex.: db.query, http.client, custom)'),
+            service: z.string().max(120).optional().describe('Só spans deste serviço (veja `services`)'),
+            name: z.string().max(200).optional().describe('Só spans cujo nome contém este texto (sem diferenciar maiúsculas)'),
+        },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId, traceId }) => guard(async () => {
+    }, async ({ projectId, traceId, spanOffset, spanLimit, kind, service, name }) => guard(async () => {
         const trace = await client.get(`/v1/projects/${projectId}/traces/${encodeURIComponent(traceId)}`);
         const t = trace;
+        const allSpans = Array.isArray(t.spans) ? t.spans : [];
+        const needle = name?.toLowerCase();
+        const matched = allSpans.filter((span) => (!kind || span.kind === kind) && (!service || span.service === service) && (!needle || (span.name ?? '').toLowerCase().includes(needle)));
+        const pageSize = clampLimit(spanLimit, maxItems).limit;
+        const spans = matched.slice(spanOffset, spanOffset + pageSize);
+        const end = spanOffset + spans.length;
+        const filters = Object.fromEntries(Object.entries({ kind, service, name }).filter(([, value]) => value !== undefined));
+        const filtered = Object.keys(filters).length > 0;
+        const spanPage = {
+            total: allSpans.length,
+            matched: matched.length,
+            offset: spanOffset,
+            returned: spans.length,
+            nextSpanOffset: end < matched.length ? end : null,
+            ...(filtered ? { filters } : {}),
+        };
         const repeated = t.summary?.repeated?.slice(0, 5).map((r) => `${r.kind} "${r.name}" ×${r.count}`).join('; ');
         // O buraco é a informação que o agente não consegue inferir da lista de spans.
         const untraced = t.summary?.untraced;
         const gapNote = untraced && untraced.totalMs > 0
             ? ` · ATENÇÃO: ${ms(untraced.totalMs)} (${Math.round(untraced.ratio * 100)}%) fora de qualquer span${t.gaps?.[0] ? `, depois de "${t.gaps[0].spanName}"` : ''}`
             : '';
-        const summary = `${t.name ?? traceId}: ${ms(t.durationMs)}, status ${t.statusCode ?? '—'}, ${t.spans?.length ?? 0} spans${repeated ? ` · repetidos: ${repeated}` : ''}${gapNote}`;
-        return json(compact(trace), summary);
+        const filterLabel = Object.entries(filters).map(([key, value]) => `${key}=${value}`).join(', ');
+        let pageNote;
+        if (matched.length === 0)
+            pageNote = filtered ? `Nenhum span casa com ${filterLabel}.` : 'Trace sem spans.';
+        else if (spans.length === 0)
+            pageNote = `spanOffset ${spanOffset} passa do fim: ${matched.length} spans${filtered ? ` com ${filterLabel}` : ''}.`;
+        else {
+            pageNote = `Spans ${spanOffset + 1}–${end} de ${matched.length}${filtered ? ` com ${filterLabel} (de ${allSpans.length} no trace)` : ''}.`;
+            if (spanPage.nextSpanOffset !== null)
+                pageNote += ` Próxima página: spanOffset: ${spanPage.nextSpanOffset}.`;
+        }
+        pageNote += cappedNote(spanLimit, pageSize);
+        const summary = `${t.name ?? traceId}: ${ms(t.durationMs)}, status ${t.statusCode ?? '—'}, ${allSpans.length} spans${repeated ? ` · repetidos: ${repeated}` : ''}${gapNote}\n${pageNote}`;
+        const { spans: _all, ...rest } = trace;
+        return json({ ...compact(rest), spanPage, spans: spans.map((span) => compact(span)) }, summary);
     }));
-    server.registerTool('track_search_logs', {
+    server.registerTool('tracker_search_logs', {
         title: 'Buscar logs',
-        description: 'Busca logs do projeto (GET /v1/projects/:id/logs). `q`: texto livre (full-text), "frase" entre aspas, key=value filtra context, ~trecho faz substring. `level` é o nível mínimo. Devolve os mais recentes primeiro.',
+        description: 'Busca logs do projeto (GET /v1/projects/:id/logs). `q`: texto livre (full-text), "frase" entre aspas, key=value filtra context, ~trecho faz substring. `level` é o nível mínimo. Filtros exatos: service, traceId, requestId, env. Devolve os mais recentes primeiro; paginado pela API (cursor = nextCursor).',
         inputSchema: {
             projectId: projectIdSchema,
             q: z.string().optional().describe('Consulta textual'),
             service: z.string().optional().describe('Nome do serviço'),
             level: z.enum(LOG_LEVELS).optional().describe('Nível mínimo: trace|debug|info|warn|error|fatal'),
             traceId: z.string().optional(),
+            requestId: z.string().max(128).optional().describe('requestId da requisição'),
+            env: z.string().max(64).optional().describe('Ambiente (ex.: production)'),
             range: z.enum(RANGE_KEYS).default('1h').describe('Janela (default 1h)'),
-            limit: z.number().int().min(1).max(200).default(50),
-            cursor: z.string().optional(),
+            limit: z.number().int().min(1).max(200).default(50).describe('Logs por página (default 50, máx. 200; até FG_TRACKER_MAX_ITEMS)'),
+            cursor: z.string().optional().describe('nextCursor da página anterior'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId, q, service, level, traceId, range, limit, cursor }) => guard(async () => {
+    }, async ({ projectId, q, service, level, traceId, requestId, env, range, limit, cursor }) => guard(async () => {
         const { from, to } = rangeWindow(range);
+        const page = clampLimit(limit, maxItems);
         let res;
         try {
-            res = await client.get(`/v1/projects/${projectId}/logs`, { from, to, q, service, level, traceId, limit, cursor, order: 'desc' });
+            res = await client.get(`/v1/projects/${projectId}/logs`, { from, to, q, service, level, traceId, requestId, env, limit: page.limit, cursor, order: 'desc' });
         }
         catch (err) {
             if (err instanceof TrackApiError && err.status === 404 && /Cannot GET/.test(err.message)) {
-                return text(`A API em ${client.baseUrl} ainda não expõe GET /v1/projects/:id/logs (endpoint de logs não disponível nesta versão). Atualize a API do FG Track.`);
+                return text(`A API em ${client.baseUrl} ainda não expõe GET /v1/projects/:id/logs (endpoint de logs não disponível nesta versão). Atualize a API do FG Tracker.`);
             }
             throw err;
         }
         if (res.items.length === 0)
-            return text(`Nenhum log no range ${range}${q ? ` para "${q}"` : ''}${service ? ` (service ${service})` : ''}.`);
-        const lines = res.items.slice(0, 25).map((l) => `${l.ts} [${l.level}] ${l.service}: ${l.message.slice(0, 160)}${l.traceId ? ` (trace ${l.traceId})` : ''}`);
-        return json(compact(res), `${res.items.length} logs${res.nextCursor ? ' (há mais: use cursor)' : ''}:\n${lines.join('\n')}`);
+            return text(`Nenhum log no range ${range}${q ? ` para "${q}"` : ''}${service ? ` (service ${service})` : ''}${env ? ` (env ${env})` : ''}${requestId ? ` (requestId ${requestId})` : ''}.`);
+        const lines = res.items.map((l) => `${l.ts} [${l.level}] ${l.service}: ${l.message.slice(0, 160)}${l.traceId ? ` (trace ${l.traceId})` : ''}`);
+        return json({ ...res, items: res.items.map((item) => compact(item)) }, `${res.items.length} logs${res.nextCursor ? ' (há mais: use cursor)' : ''}:${cappedNote(limit, page.limit)}\n${preview(lines)}`);
     }));
-    server.registerTool('track_instrumentation_guide', {
+    server.registerTool('tracker_instrumentation_guide', {
         title: 'Guia de instrumentação',
-        description: 'Passo a passo com código copiável para conectar um app ao FG Track: express, nestjs, nextjs, fastify (via hook), pino ou winston (logs). Com projectId, o código já vem com a apiKey real do projeto.',
+        description: 'Passo a passo com código copiável para conectar um app ao FG Tracker: express, nestjs, nextjs, fastify (via hook), pino ou winston (logs). Com projectId, o código já vem com a apiKey real do projeto.',
         inputSchema: {
             framework: z.enum(FRAMEWORKS).describe('express | nestjs | nextjs | fastify | pino | winston'),
             projectId: z.string().uuid().optional().describe('Projeto para usar a chave real (recomendado)'),
             serviceName: z.string().optional().describe('serviceName do tracker (default: slug do projeto)'),
-            databaseDriver: z.string().optional().describe('Driver returned by track_detect_databases; never assume pg for other clients'),
+            databaseDriver: z.string().optional().describe('Driver returned by tracker_detect_databases; never assume pg for other clients'),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async ({ framework, projectId, serviceName, databaseDriver }) => guard(async () => {
@@ -252,9 +470,9 @@ export function createServer(options = {}) {
             projectId: project?.id,
             serviceName: serviceName ?? project?.slug,
         });
-        return text(guide + '\n\n' + (databaseDriver ? databaseGuide(databaseDriver, serviceName ?? project?.slug ?? 'app') : 'Before instrumenting any database call track_detect_databases with the local project path. The pg examples only apply to pg.Pool, never to Postgres.js/Prisma/other drivers.'));
+        return text(guide + '\n\n' + (databaseDriver ? databaseGuide(databaseDriver, serviceName ?? project?.slug ?? 'app') : 'Before instrumenting any database call tracker_detect_databases with the local project path. The pg examples only apply to pg.Pool, never to Postgres.js/Prisma/other drivers.'));
     }));
-    server.registerTool('track_verify_ingest', {
+    server.registerTool('tracker_verify_ingest', {
         title: 'Verificar ingestão',
         description: 'Confirma se spans e logs do projeto chegaram recentemente (últimos 15 min): consulta o trace e o log mais recentes e explica o que fazer se nada chegou.',
         inputSchema: { projectId: projectIdSchema },
@@ -297,18 +515,18 @@ export function createServer(options = {}) {
         }
         lines.push('');
         if (spansOk) {
-            lines.push(`Veredito: ingestão de traces funcionando${logsOk ? ' e logs chegando' : logsAvailable ? '; logs ainda não (opcional)' : ''}. Explore com track_get_overview { projectId: "${projectId}", range: "15m" } e track_list_issues.`);
+            lines.push(`Veredito: ingestão de traces funcionando${logsOk ? ' e logs chegando' : logsAvailable ? '; logs ainda não (opcional)' : ''}. Explore com tracker_get_overview { projectId: "${projectId}", range: "15m" } e tracker_list_issues.`);
         }
         else {
-            lines.push('Veredito: nada chegou. Checklist:', `1. O app está rodando e recebeu requisições nos últimos minutos? (o SDK envia a cada 2 s; chame tracker.flush() para forçar)`, `2. FG_TRACKER_KEY é a chave deste projeto? (track_list_projects mostra a apiKey; resposta 4xx no envio = chave errada, o SDK avisa uma vez no console)`, `3. O app alcança a API? (curl ${client.baseUrl}/v1/health de dentro do ambiente do app; endpoint do tracker = FG_TRACKER_URL)`, '4. app.use(tracker.express()) é o PRIMEIRO middleware / wrapNextRoute envolve o handler / hook onRequest registrado antes das rotas?', '5. createTracker recebeu enabled: false ou apiKey vazia? (tracker vira no-op com aviso "[fg-tracker] apiKey ausente")', `Teste direto sem o SDK: curl -X POST ${client.baseUrl}/v1/ingest -H 'x-fg-tracker-key: <apiKey>' -H 'content-type: application/json' -d '{"traces":[...]}' (formato em ${QUICKSTART_URI}).`);
+            lines.push('Veredito: nada chegou. Checklist:', `1. O app está rodando e recebeu requisições nos últimos minutos? (o SDK envia a cada 2 s; chame tracker.flush() para forçar)`, `2. FG_TRACKER_KEY é a chave deste projeto? (tracker_list_projects mostra a apiKey; resposta 4xx no envio = chave errada, o SDK avisa uma vez no console)`, `3. O app alcança a API? (curl ${client.baseUrl}/v1/health de dentro do ambiente do app; endpoint do tracker = FG_TRACKER_URL)`, '4. app.use(tracker.express()) é o PRIMEIRO middleware / wrapNextRoute envolve o handler / hook onRequest registrado antes das rotas?', '5. createTracker recebeu enabled: false ou apiKey vazia? (tracker vira no-op com aviso "[fg-tracker] apiKey ausente")', `Teste direto sem o SDK: curl -X POST ${client.baseUrl}/v1/ingest -H 'x-fg-tracker-key: <apiKey>' -H 'content-type: application/json' -d '{"traces":[...]}' (formato em ${QUICKSTART_URI}).`);
         }
         return text(lines.join('\n'));
     }));
     /* ---------------- releases, issues, monitores, provedores (CONTRATO.md §15–§20) ---------------- */
-    server.registerTool('track_get_issue', {
+    server.registerTool('tracker_get_issue', {
         title: 'Detalhe de uma issue',
         description: 'Issue estilo Sentry: ocorrências recentes (timestamp, trace, usuário, release), ocorrências por dia, usuários mais afetados, releases em que apareceu, regressões (resolvida que voltou) e commits/PRs suspeitos (frames do stack cruzados com os arquivos alterados nas releases).',
-        inputSchema: { projectId: projectIdSchema, issueId: z.string().uuid().describe('id da issue (track_list_issues)') },
+        inputSchema: { projectId: projectIdSchema, issueId: z.string().uuid().describe('id da issue (tracker_list_issues)') },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async ({ projectId, issueId }) => guard(async () => {
         const issue = await client.get(`/v1/projects/${projectId}/issues/${issueId}`);
@@ -317,24 +535,39 @@ export function createServer(options = {}) {
         const summary = `${i.title}: ×${i.count ?? 0}, ${i.impact?.usersAffected ?? 0} usuários, ${i.impact?.occurrences24h ?? 0} em 24h${i.firstRelease ? ` · desde ${i.firstRelease}` : ''}${i.regressedRelease ? ` · regressão em ${i.regressedRelease}` : ''}${suspects ? `\nCommits suspeitos:\n${suspects}` : ''}`;
         return json(compact(issue), summary);
     }));
-    server.registerTool('track_list_releases', {
+    server.registerTool('tracker_list_releases', {
         title: 'Releases e saúde por versão',
-        description: 'Releases/deploys do projeto com requests, taxa de erro, p95, issues novas, regressões e variação vs. a release anterior. Com `version`, devolve o detalhe: commits, comparação de endpoints com a anterior e issues.',
-        inputSchema: { projectId: projectIdSchema, version: z.string().optional().describe('Versão exata para o detalhe') },
+        description: 'Releases/deploys do projeto com requests, taxa de erro, p95, issues novas, regressões, ambientes e variação vs. a release anterior (mais recentes primeiro; a API devolve até 100, sem cursor). Com `version`, devolve o detalhe: commits, comparação de endpoints com a anterior e issues.',
+        inputSchema: {
+            projectId: projectIdSchema,
+            version: z.string().optional().describe('Versão exata para o detalhe'),
+            environment: z.string().max(64).optional().describe('Só releases vistas/registradas neste ambiente, com saúde calculada nele'),
+            limit: z.number().int().min(1).max(100).default(30).describe('Máximo de releases (default 30, máx. 100; até FG_TRACKER_MAX_ITEMS)'),
+        },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId, version }) => guard(async () => {
+    }, async ({ projectId, version, environment, limit }) => guard(async () => {
         if (version) {
-            const detail = await client.get(`/v1/projects/${projectId}/releases/${encodeURIComponent(version)}`);
+            const detail = await client.get(`/v1/projects/${projectId}/releases/${encodeURIComponent(version)}`, { environment });
             const d = detail;
-            return json(compact(detail), `${version}: ${d.health?.requests ?? 0} req · erro ${pct(d.health?.errorRate)} · p95 ${ms(d.health?.p95Ms)} · ${d.health?.newIssues ?? 0} issues novas · ${d.health?.regressions ?? 0} regressões · ${d.commits?.length ?? 0} commits`);
+            const envNote = environment && d.environments === undefined ? '\nATENÇÃO: esta API não filtra releases por ambiente; a saúde acima inclui todos os ambientes.' : '';
+            return json(compact(detail), `${version}${environment ? ` (${environment})` : ''}: ${d.health?.requests ?? 0} req · erro ${pct(d.health?.errorRate)} · p95 ${ms(d.health?.p95Ms)} · ${d.health?.newIssues ?? 0} issues novas · ${d.health?.regressions ?? 0} regressões · ${d.commits?.length ?? 0} commits${envNote}`);
         }
-        const releases = await client.get(`/v1/projects/${projectId}/releases`);
+        const page = clampLimit(limit, maxItems);
+        const releases = await client.get(`/v1/projects/${projectId}/releases`, { limit: page.limit, environment });
         if (releases.length === 0)
-            return text('Nenhuma release. Configure `release` no SDK ou registre deploys com track_register_release / fg-tracker-release.');
-        const lines = releases.slice(0, 25).map((r) => `- ${r.version}${r.isCurrent ? ' (atual)' : ''} · ${ago(r.deployedAt ?? r.firstSeen ?? new Date().toISOString())} · ${r.health.requests} req · erro ${pct(r.health.errorRate)} · p95 ${ms(r.health.p95Ms)}${r.delta.p95Ms !== null ? ` (${r.delta.p95Ms >= 0 ? '+' : ''}${Math.round(r.delta.p95Ms * 100)}%)` : ''} · ${r.health.newIssues} novas · ${r.health.regressions} regressões`);
-        return json(compact(releases), `${releases.length} releases:\n${lines.join('\n')}`);
+            return text(environment ? `Nenhuma release no ambiente ${environment}.` : 'Nenhuma release. Configure `release` no SDK ou registre deploys com tracker_register_release / fg-tracker-release.');
+        const envs = (r) => {
+            const names = r.environments ? r.environments.map((e) => e.environment) : r.environment ? [r.environment] : [];
+            return names.length ? ` · [${names.join(', ')}]` : '';
+        };
+        const lines = releases.map((r) => `- ${r.version}${r.isCurrent ? ' (atual)' : ''}${envs(r)} · ${ago(r.deployedAt ?? r.firstSeen ?? new Date().toISOString())} · ${r.health.requests} req · erro ${pct(r.health.errorRate)} · p95 ${ms(r.health.p95Ms)}${r.delta.p95Ms !== null ? ` (${r.delta.p95Ms >= 0 ? '+' : ''}${Math.round(r.delta.p95Ms * 100)}%)` : ''} · ${r.health.newIssues} novas · ${r.health.regressions} regressões`);
+        const notes = [
+            environment && !releases.some((r) => r.environments !== undefined) ? `ATENÇÃO: esta API não filtra releases por ambiente; a lista e a saúde abaixo incluem todos os ambientes.` : '',
+            releases.length >= page.limit ? `Limite de ${page.limit} atingido: pode haver releases mais antigas${page.limit < 100 ? ' (aumente limit até 100)' : ' (a API devolve no máximo 100)'}.${cappedNote(limit, page.limit)}` : '',
+        ].filter(Boolean);
+        return json(releases.map((r) => compact(r)), `${releases.length} releases${environment ? ` (${environment})` : ''}:\n${preview(lines)}${notes.length ? `\n${notes.join('\n')}` : ''}`);
     }));
-    server.registerTool('track_register_release', {
+    server.registerTool('tracker_register_release', {
         title: 'Registrar release/deploy',
         description: 'Registra uma release no projeto (POST /v1/projects/:id/releases) com versão, SHA, repositório e commits opcionais. Para enviar commits e arquivos alterados a partir do git, prefira o CLI `fg-tracker-release` (pacote fg-tracker-sdk) no passo de deploy.',
         inputSchema: {
@@ -352,7 +585,7 @@ export function createServer(options = {}) {
         const release = await client.post(`/v1/projects/${projectId}/releases`, body);
         return json(compact(release), `Release ${body.version} registrada.`);
     }));
-    server.registerTool('track_endpoint_history', {
+    server.registerTool('tracker_endpoint_history', {
         title: 'Histórico de latência de uma rota',
         description: 'Rollups horários (até 400 dias) de uma rota: série de média/p50/p95/p99, comparação da janela atual com a anterior e média/p95 por release — para saber se as mudanças melhoraram ou pioraram o tempo de resposta.',
         inputSchema: { projectId: projectIdSchema, name: z.string().min(1).describe('Nome exato do endpoint (ex.: "GET /users/:id")'), days: z.number().int().min(1).max(400).default(30) },
@@ -364,7 +597,7 @@ export function createServer(options = {}) {
         const byRelease = (h.releases ?? []).map((r) => `- ${r.release}: média ${ms(r.avgMs)} · p95 ${ms(r.p95Ms)} (${fmt(r.deltaP95)} vs. anterior)`).join('\n');
         return json(compact(history), `${name} (${days}d): média ${ms(h.current?.avgMs)} (${fmt(h.delta?.avgMs)}), p95 ${ms(h.current?.p95Ms)} (${fmt(h.delta?.p95Ms)}) vs. janela anterior (média ${ms(h.previous?.avgMs)}, p95 ${ms(h.previous?.p95Ms)}).${byRelease ? `\nPor release:\n${byRelease}` : ''}`);
     }));
-    server.registerTool('track_list_providers', {
+    server.registerTool('tracker_list_providers', {
         title: 'Provedores externos (chamadas de saída)',
         description: 'Chamadas http.client agregadas por host no range (OpenRouter, Mureka, Stripe…): requests, taxa de erro, p50/p95, tempo total, operações mais chamadas e endpoints que as disparam.',
         inputSchema: { projectId: projectIdSchema, range: rangeSchema },
@@ -376,7 +609,7 @@ export function createServer(options = {}) {
         const lines = providers.items.slice(0, 25).map((p) => `- ${p.host}: ${p.requests} chamadas · erro ${pct(p.errorRate)} · p95 ${ms(p.p95Ms)} · total ${ms(p.totalMs)}`);
         return json(compact(providers), `${providers.items.length} hosts, ${providers.totalRequests} chamadas, erro ${pct(providers.errorRate)}:\n${lines.join('\n')}`);
     }));
-    server.registerTool('track_traffic_summary', {
+    server.registerTool('tracker_traffic_summary', {
         title: 'Tráfego (pageviews) do projeto',
         description: 'Visitantes únicos, sessões, pageviews, bounce e duração média por dia (UTC) vindos do SDK de navegador com analytics: true, mais top páginas, referrers, UTM, dispositivo e país. Rollup diário atualizado de hora em hora.',
         inputSchema: { projectId: projectIdSchema, days: z.number().int().min(1).max(400).default(30).describe('Últimos N dias, incluindo hoje') },
@@ -386,8 +619,48 @@ export function createServer(options = {}) {
         const day = (offset) => new Date(now - offset * 86_400_000).toISOString().slice(0, 10);
         const traffic = await client.get(`/v1/projects/${projectId}/traffic`, { from: day(days - 1), to: day(0), limit: 5 });
         const t = traffic.totals;
-        if (t.pageviews === 0)
-            return text(`Nenhum pageview nos últimos ${days} dias. Ligue analytics: true no fg-tracker-browser (docs/instalar-pageviews.md); o rollup roda de hora em hora.`);
+        if (t.pageviews === 0) {
+            // Janela vazia não quer dizer analytics desligado: o dia UTC pode não ter
+            // passado pelo rollup ainda, ou os dados estão antes da janela.
+            const TRAFFIC_MAX_DAYS = 400; // maior janela de GET /v1/projects/:id/traffic
+            const from = day(days - 1);
+            const lines = [`Nenhum pageview de ${from} a ${day(0)} (dias UTC).`];
+            const rollupAt = traffic.lastRollupAt;
+            // Sem rollup em dia, janela e histórico vazios não provam que nada chegou.
+            const rollupPending = !rollupAt || Date.parse(rollupAt) < Date.parse(`${from}T00:00:00Z`);
+            if (!rollupAt)
+                lines.push('O rollup de tráfego ainda não rodou nesta API (roda de hora em hora); pageviews recebidos só aparecem depois dele.');
+            else if (Date.parse(rollupAt) < Date.parse(`${from}T00:00:00Z`))
+                lines.push(`O último rollup foi ${ago(rollupAt, now)} (${rollupAt}), antes do início da janela: os pageviews desses dias (UTC) ainda não foram processados. O rollup roda de hora em hora.`);
+            else
+                lines.push(`Último rollup ${ago(rollupAt, now)}.`);
+            let lastDay;
+            let historyChecked = false;
+            if (days < TRAFFIC_MAX_DAYS) {
+                try {
+                    const history = await client.get(`/v1/projects/${projectId}/traffic`, { from: day(TRAFFIC_MAX_DAYS - 1), to: day(days), dims: 'path', limit: 1 });
+                    historyChecked = true;
+                    lastDay = [...(history.days ?? [])].reverse().find((d) => d.pageviews > 0);
+                }
+                catch {
+                    /* sem histórico: cai na mensagem genérica */
+                }
+            }
+            if (lastDay) {
+                const span = Math.round((Date.parse(day(0)) - Date.parse(lastDay.day)) / 86_400_000) + 1;
+                lines.push(`Analytics já enviou dados: o último dia com pageviews é ${lastDay.day} (${lastDay.pageviews}). Amplie a janela, ex.: days: ${span}.`);
+            }
+            else if (rollupPending) {
+                lines.push('Nenhum pageview processado no histórico, mas com o rollup pendente isso não prova que nada chegou. Consulte de novo depois do próximo rollup antes de concluir que analytics está desligado.');
+            }
+            else if (historyChecked || days >= TRAFFIC_MAX_DAYS) {
+                lines.push(`Nenhum pageview processado nos últimos ${TRAFFIC_MAX_DAYS} dias até o último rollup. Se o site começou a enviar depois dele, aguarde o próximo; senão, ligue analytics: true no fg-tracker-browser (docs/instalar-pageviews.md) e confira se o domínio do site está nos domínios permitidos (tracker_list_projects).`);
+            }
+            else {
+                lines.push(`Se o site nunca enviou pageviews, ligue analytics: true no fg-tracker-browser (docs/instalar-pageviews.md); se já enviou, amplie a janela com days.`);
+            }
+            return text(lines.join('\n'));
+        }
         const top = (dim, label) => {
             const items = traffic.dims[dim] ?? [];
             return items.length ? `${label}: ${items.map((i) => `${i.value} (${i.pageviews})`).join(', ')}` : '';
@@ -395,17 +668,87 @@ export function createServer(options = {}) {
         const lines = [top('path', 'Páginas'), top('referrer', 'Referrers'), top('utm_source', 'UTM source'), top('utm_campaign', 'Campanhas')].filter(Boolean);
         return json(compact(traffic), `Últimos ${days} dias: ${t.visitors} visitantes (soma diária), ${t.sessions} sessões, ${t.pageviews} pageviews, bounce ${pct(t.bounceRate)}, ${t.pagesPerSession} páginas/sessão, sessão média ${Math.round(t.avgSessionSeconds)} s.${traffic.lastRollupAt ? ` Último rollup ${ago(traffic.lastRollupAt)}.` : ''}\n${lines.join('\n')}`);
     }));
-    server.registerTool('track_list_monitors', {
+    server.registerTool('tracker_list_monitors', {
         title: 'Monitores (uptime e jobs)',
-        description: 'Monitores de uptime HTTP e check-ins de jobs agendados: status (ok, down, missed, pending, paused), uptime 30d, último erro e próximo prazo.',
-        inputSchema: { projectId: projectIdSchema },
+        description: 'Monitores de uptime HTTP e check-ins de jobs agendados: id, ambiente, status (ok, down, missed, pending, paused), uptime 30d, último erro, próximo prazo e o trace da última execução que reportou um. Histórico de checks: tracker_get_monitor.',
+        inputSchema: {
+            projectId: projectIdSchema,
+            environment: z.string().max(64).optional().describe('Só monitores deste ambiente (API com ambientes)'),
+        },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async ({ projectId }) => guard(async () => {
-        const monitors = await client.get(`/v1/projects/${projectId}/monitors`);
-        if (monitors.length === 0)
-            return text('Nenhum monitor. Crie um uptime no painel ou envie um check-in: tracker.checkIn(slug, fn) / GET /v1/monitors/:slug/ping?status=ok.');
-        const lines = monitors.map((m) => `- [${m.status}] ${m.name} (${m.kind}, ${m.slug})${m.uptime30d !== null ? ` · uptime ${pct(m.uptime30d)}` : ''}${m.lastCheckAt ? ` · último check ${ago(m.lastCheckAt)}` : ''}${m.lastError ? ` · ${m.lastError}` : ''}`);
-        return json(compact(monitors), `${monitors.length} monitores:\n${lines.join('\n')}`);
+    }, async ({ projectId, environment }) => guard(async () => {
+        const all = await client.get(`/v1/projects/${projectId}/monitors`, { environment });
+        const envSupported = all.some((m) => 'environment' in m);
+        const monitors = environment && envSupported ? all.filter((m) => m.environment === environment) : all;
+        if (monitors.length === 0) {
+            return text(environment ? `Nenhum monitor no ambiente ${environment}.` : 'Nenhum monitor. Crie um uptime no painel ou envie um check-in: tracker.checkIn(slug, fn) / GET /v1/monitors/:slug/ping?status=ok.');
+        }
+        const items = monitors.map(({ recent, ...m }) => {
+            const traced = lastTraced(recent);
+            return { ...m, lastTraceId: traced?.traceId ?? null, lastTraceAt: traced?.at ?? null, lastRelease: traced?.release ?? null };
+        });
+        const page = listPage(items, maxItems);
+        const lines = items.slice(0, maxItems).map((m) => `- ${monitorLabel(m)} · id ${m.id}${m.superseded ? ' · substituído pelos monitores por ambiente' : ''}${m.uptime30d !== null ? ` · uptime ${pct(m.uptime30d)}` : ''}${m.lastCheckAt ? ` · último check ${ago(m.lastCheckAt)}` : ''}${m.lastTraceId ? ` · último trace ${m.lastTraceId}` : ''}${m.lastError ? ` · ${m.lastError}` : ''}`);
+        const notes = [
+            environment && !envSupported ? 'ATENÇÃO: esta API não separa monitores por ambiente; o filtro environment não foi aplicado.' : '',
+            page.truncated ? `Mostrando ${page.returned} de ${page.total} monitores (FG_TRACKER_MAX_ITEMS=${maxItems}).` : '',
+        ].filter(Boolean);
+        return json(page, `${monitors.length} monitores:\n${preview(lines)}${notes.length ? `\n${notes.join('\n')}` : ''}`);
+    }));
+    server.registerTool('tracker_get_monitor', {
+        title: 'Detalhe de um monitor (histórico de checks)',
+        description: 'Histórico de checks de um monitor, mais recentes primeiro: status, duração, status HTTP, erro, origem e, nas execuções de jobs, o traceId (abra com tracker_get_trace) e a release. ' +
+            'Informe monitorId (tracker_list_monitors) ou slug; o slug só é aceito quando identifica um único monitor do projeto (use environment para desambiguar).',
+        inputSchema: {
+            projectId: projectIdSchema,
+            monitorId: z.string().uuid().optional().describe('id do monitor (tracker_list_monitors)'),
+            slug: z.string().min(1).max(120).optional().describe('slug do monitor, alternativa a monitorId'),
+            environment: z.string().max(64).optional().describe('Ambiente do monitor, para desambiguar um slug usado em mais de um'),
+            limit: z.number().int().min(1).max(500).default(50).describe('Checks do histórico (default 50, máx. 500; até FG_TRACKER_MAX_ITEMS)'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ projectId, monitorId, slug, environment, limit }) => guard(async () => {
+        if (Boolean(monitorId) === Boolean(slug))
+            throw new Error('Informe monitorId ou slug (só um dos dois).');
+        let id = monitorId;
+        if (!id) {
+            const monitors = await client.get(`/v1/projects/${projectId}/monitors`);
+            let matches = monitors.filter((m) => m.slug === slug);
+            if (environment && matches.some((m) => 'environment' in m))
+                matches = matches.filter((m) => m.environment === environment);
+            if (matches.length === 0) {
+                const slugs = [...new Set(monitors.map((m) => m.slug))];
+                throw new Error(`Nenhum monitor com slug "${slug}"${environment ? ` no ambiente ${environment}` : ''} neste projeto.${slugs.length ? ` Slugs: ${slugs.slice(0, 25).join(', ')}${slugs.length > 25 ? ` (+${slugs.length - 25})` : ''}.` : ''}`);
+            }
+            if (matches.length > 1) {
+                throw new Error(`O slug "${slug}" identifica ${matches.length} monitores; repita com monitorId${matches.some((m) => 'environment' in m) ? ' ou environment' : ''}:\n` +
+                    matches.map((m) => `- ${m.id} · ${monitorLabel(m)}`).join('\n'));
+            }
+            id = matches[0].id;
+        }
+        const page = clampLimit(limit, maxItems);
+        const detail = await client.get(`/v1/projects/${projectId}/monitors/${id}`, { limit: page.limit });
+        const { recent: _recent, checks = [], ...monitor } = detail;
+        let envNote = '';
+        if (environment) {
+            // Sem ambiente na resposta (API antiga), o histórico pode misturar ambientes.
+            if (!('environment' in detail))
+                envNote = '\nATENÇÃO: esta API não separa monitores por ambiente; o filtro environment não foi aplicado e o histórico pode misturar ambientes.';
+            else if (detail.environment !== environment)
+                throw new Error(`O monitor ${detail.id} é do ambiente ${detail.environment ?? '(sem ambiente)'}, não de ${environment}.`);
+        }
+        const head = [
+            `${monitorLabel(detail)} · id ${detail.id}`,
+            detail.uptime30d !== null ? `uptime 30d ${pct(detail.uptime30d)}` : '',
+            detail.lastCheckAt ? `último check ${ago(detail.lastCheckAt)}` : '',
+            detail.runningSince ? `rodando desde ${detail.runningSince}` : '',
+            detail.nextDueAt ? `próximo prazo ${until(detail.nextDueAt)}` : '',
+            detail.lastError ? `último erro: ${detail.lastError}` : '',
+        ].filter(Boolean).join(' · ');
+        const lines = checks.map((c) => `- ${c.at} ${c.status}${c.durationMs !== null ? ` · ${ms(c.durationMs)}` : ''}${c.statusCode !== null ? ` · HTTP ${c.statusCode}` : ''}${c.traceId ? ` · trace ${c.traceId}` : ''}${c.release ? ` · release ${c.release}` : ''}${c.error ? ` · ${c.error.slice(0, 160)}` : ''}`);
+        const more = checks.length >= page.limit ? `\nLimite de ${page.limit} checks atingido: pode haver checks mais antigos${page.limit < 500 ? ' (aumente limit até 500)' : ' (a API devolve no máximo 500)'}.${cappedNote(limit, page.limit)}` : '';
+        const history = checks.length ? `${checks.length} checks (mais recentes primeiro):\n${preview(lines)}${more}` : 'Nenhum check registrado.';
+        return json({ ...compact(monitor), checks: checks.map((c) => compact(c)) }, `${head}\n${history}${envNote}`);
     }));
     /* ---------------- infraestrutura (CONTRATO.md §27.9) ---------------- */
     registerInfraTools(server, client, SERVER_VERSION);
@@ -413,10 +756,10 @@ export function createServer(options = {}) {
     registerLoadtestTools(server, client);
     /* ---------------- prompt ---------------- */
     server.registerPrompt('instrument-project', {
-        title: 'Conectar projeto ao FG Track',
-        description: 'Plano passo a passo para um agente de código instrumentar o projeto atual: detectar framework/logger → criar/escolher projeto → instalar SDK → tracker + pg + fetch + logs → env → rodar → track_verify_ingest → corrigir.',
+        title: 'Conectar projeto ao FG Tracker',
+        description: 'Plano passo a passo para um agente de código instrumentar o projeto atual: detectar framework/logger → criar/escolher projeto → instalar SDK → tracker + pg + fetch + logs → env → rodar → tracker_verify_ingest → corrigir.',
         argsSchema: {
-            projectName: z.string().optional().describe('Nome do projeto no FG Track (default: nome do pacote)'),
+            projectName: z.string().optional().describe('Nome do projeto no FG Tracker (default: nome do pacote)'),
             framework: z.string().optional().describe('express | nestjs | nextjs | fastify (default: detectar)'),
         },
     }, ({ projectName, framework }) => ({
@@ -429,7 +772,7 @@ export function createServer(options = {}) {
     }));
     /* ---------------- resource ---------------- */
     server.registerResource('quickstart', QUICKSTART_URI, {
-        title: 'FG Track quickstart',
+        title: 'FG Tracker quickstart',
         description: 'Guia rápido (markdown): projeto e chave, SDK, logs, ingestão crua, verificação e detectores.',
         mimeType: 'text/markdown',
     }, async (uri) => ({
@@ -437,7 +780,7 @@ export function createServer(options = {}) {
     }));
     // URI antiga (stread-track-mcp ≤ 0.3): mesmo conteúdo, mantida até a 1.0.
     server.registerResource('quickstart-legacy', LEGACY_QUICKSTART_URI, {
-        title: 'FG Track quickstart (URI obsoleta)',
+        title: 'FG Tracker quickstart (URI obsoleta)',
         description: `Obsoleto: use ${QUICKSTART_URI}. Mesmo conteúdo do quickstart.`,
         mimeType: 'text/markdown',
     }, async (uri) => ({