fg-tracker-mcp 0.10.0 → 0.11.0

package/dist/inputs.js

@@ -0,0 +1,30 @@
+/** Parâmetros de entrada comuns às ferramentas tracker_* (o mesmo texto em todas). */
+import { z } from 'zod';
+import { RANGE_KEYS } from './client.js';
+export const rangeSchema = z.enum(RANGE_KEYS).default('24h').describe('Janela: 15m|1h|6h|24h|7d|30d (default 24h)');
+export const projectIdSchema = z.string().uuid().describe('ID (uuid) do projeto — veja tracker_list_projects');
+export const rootKindSchema = z
+    .enum(['http', 'custom', 'browser', 'all'])
+    .optional()
+    .describe('Tipo da raiz: http = requisições (default), custom = jobs/tarefas (tracker.span("custom", ...) sem pai), browser = raízes do SDK de navegador, all = qualquer raiz');
+export 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)');
+export const envFilterSchema = z.string().min(1).max(64).optional().describe('Só execuções deste ambiente (environment da raiz, igualdade exata; valores em tracker_list_environments)');
+/** Instante ISO 8601 com fuso (`2026-10-15T09:00:00Z`, `2026-10-15T06:00:00-03:00`). */
+export const isoInstantSchema = z.string().datetime({ offset: true });
+/** `from`/`to` absolutos das leituras de métricas (a API aceita até 31 dias; `range` vale quando falta `from`). */
+export const fromSchema = isoInstantSchema.optional().describe('Início absoluto ISO 8601 (ex.: 2026-10-15T09:00:00Z); com from/to o range só vale quando falta from. Até 31 dias');
+export const toSchema = isoInstantSchema.optional().describe('Fim absoluto ISO 8601 (default agora)');
+/** Descreve os filtros de raiz aplicados, para as mensagens de resumo. */
+export 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(', ')})` : '';
+}
+/** Filtros de raiz informados (sem as chaves ausentes), para o `structuredContent`. */
+export function definedFilters(filters) {
+    return Object.fromEntries(Object.entries(filters).filter(([, value]) => value !== undefined));
+}
+//# sourceMappingURL=inputs.js.map

package/dist/inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.js","sourceRoot":"","sources":["../src/inputs.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAiB,MAAM,aAAa,CAAC;AAExD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,CAAC,UAAuC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC,CAAC;AACjJ,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC,CAAC;AAC/G,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;KAC1C,QAAQ,EAAE;KACV,QAAQ,CAAC,oKAAoK,CAAC,CAAC;AAClL,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kHAAkH,CAAC,CAAC;AACtM,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0GAA0G,CAAC,CAAC;AAEzL,wFAAwF;AACxF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAEtE,mHAAmH;AACnH,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kHAAkH,CAAC,CAAC;AACnL,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC,CAAC;AAEtG,0EAA0E;AAC1E,MAAM,UAAU,UAAU,CAAC,OAA8D;IACvF,MAAM,KAAK,GAAG;QACZ,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE;QACrF,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE;QACnD,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE;KACxC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,cAAc,CAAC,OAA8D;IAC3F,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAA0D,CAAC;AACzJ,CAAC"}

package/dist/journeys.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Prompts das cinco jornadas de diagnóstico (docs/mcp.md, "Jornadas de diagnóstico"): cada um
+ * dá a sequência de ferramentas (até 6 chamadas), o critério de parada e como citar a evidência.
+ * Só usam ferramentas de leitura: valem com token pessoal `fgt_…` e com FG_TRACKER_READ_ONLY=1.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+export interface JourneyArgs {
+    projectId?: string;
+    endpoint?: string;
+    release?: string;
+    env?: string;
+    query?: string;
+    monitor?: string;
+    deployedAt?: string;
+}
+export declare function regressionPrompt(args: JourneyArgs): string;
+export declare function slowQueryPrompt(args: JourneyArgs): string;
+export declare function lateJobPrompt(args: JourneyArgs): string;
+export declare function distributedErrorPrompt(args: JourneyArgs): string;
+export declare function confirmFixPrompt(args: JourneyArgs): string;
+export declare const JOURNEYS: readonly [{
+    readonly name: "investigar-regressao-p95";
+    readonly title: "Investigar regressão de p95 após um deploy";
+    readonly build: typeof regressionPrompt;
+    readonly args: {
+        readonly projectId: z.ZodOptional<z.ZodString>;
+        readonly endpoint: z.ZodOptional<z.ZodString>;
+        readonly release: z.ZodOptional<z.ZodString>;
+        readonly env: z.ZodOptional<z.ZodString>;
+    };
+}, {
+    readonly name: "investigar-query-lenta";
+    readonly title: "Investigar query lenta ou N+1";
+    readonly build: typeof slowQueryPrompt;
+    readonly args: {
+        readonly projectId: z.ZodOptional<z.ZodString>;
+        readonly query: z.ZodOptional<z.ZodString>;
+        readonly env: z.ZodOptional<z.ZodString>;
+    };
+}, {
+    readonly name: "investigar-job-atrasado";
+    readonly title: "Investigar job atrasado ou que não rodou";
+    readonly build: typeof lateJobPrompt;
+    readonly args: {
+        readonly projectId: z.ZodOptional<z.ZodString>;
+        readonly monitor: z.ZodOptional<z.ZodString>;
+        readonly env: z.ZodOptional<z.ZodString>;
+    };
+}, {
+    readonly name: "investigar-erro-distribuido";
+    readonly title: "Investigar erro distribuído (API → serviços)";
+    readonly build: typeof distributedErrorPrompt;
+    readonly args: {
+        readonly projectId: z.ZodOptional<z.ZodString>;
+        readonly endpoint: z.ZodOptional<z.ZodString>;
+        readonly env: z.ZodOptional<z.ZodString>;
+    };
+}, {
+    readonly name: "confirmar-correcao";
+    readonly title: "Confirmar que uma correção funcionou";
+    readonly build: typeof confirmFixPrompt;
+    readonly args: {
+        readonly projectId: z.ZodOptional<z.ZodString>;
+        readonly endpoint: z.ZodOptional<z.ZodString>;
+        readonly release: z.ZodOptional<z.ZodString>;
+        readonly deployedAt: z.ZodOptional<z.ZodString>;
+        readonly env: z.ZodOptional<z.ZodString>;
+    };
+}];
+export declare function registerJourneyPrompts(server: McpServer): void;

package/dist/journeys.js

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+const COMMON_RULES = [
+    'Regras:',
+    '- No máximo 6 chamadas de ferramenta. Não abra o painel: tudo sai das ferramentas tracker_*.',
+    '- Toda conclusão cita pelo menos um item de `evidence` (traceId, spanId quando houver, métrica, valor e janela) devolvido por uma ferramenta nesta conversa. Sem evidência, diga que não há dado suficiente, não chute.',
+    '- Se o projeto tem mais de um ambiente, filtre por env (tracker_list_environments diz quais existem). Quando uma resposta trouxer `filtersApplied: false`, avise que os números misturam ambientes.',
+    '- Percentis de janelas longas (tracker_endpoint_history, releases) podem ser aproximados nesta API; prefira os traces e tracker_get_endpoint para a janela recente.',
+];
+function header(title, args) {
+    const known = [
+        args.projectId ? `projectId ${args.projectId}` : 'projectId: descubra com tracker_list_projects (não conta como passo se o usuário já informou)',
+        args.env ? `ambiente ${args.env}` : '',
+        args.endpoint ? `endpoint/job "${args.endpoint}"` : '',
+        args.release ? `release ${args.release}` : '',
+        args.query ? `query contendo "${args.query}"` : '',
+        args.monitor ? `monitor ${args.monitor}` : '',
+        args.deployedAt ? `deploy em ${args.deployedAt}` : '',
+    ].filter(Boolean);
+    return [`# ${title}`, '', `Dados: ${known.join(' · ')}.`, ''];
+}
+const p = (args) => (args.projectId ? `"${args.projectId}"` : '<projectId>');
+const envArg = (args, key = 'env') => (args.env ? `, ${key}: "${args.env}"` : '');
+export function regressionPrompt(args) {
+    const name = args.endpoint ? `"${args.endpoint}"` : '<rota com maior delta>';
+    return [
+        ...header('Investigar regressão de p95 depois de um deploy', args),
+        'Objetivo: dizer qual rota piorou, em qual release, e onde o tempo a mais está (banco, chamada externa, código sem span), com traces de prova.',
+        '',
+        'Sequência:',
+        `1. tracker_list_releases { projectId: ${p(args)}${envArg(args, 'environment')} } — ${args.release ? `a release ${args.release} e a anterior a ela` : 'a release com maior delta de p95 e a anterior a ela'}.`,
+        `2. tracker_compare { projectId: ${p(args)}, a: { release: <anterior> }, b: { release: ${args.release ? `"${args.release}"` : '<nova>'} }${args.endpoint ? `, endpoint: "${args.endpoint}"` : ''}${envArg(args)} } — rotas que mais pioraram, onde o tempo cresceu por tipo de span (banco, chamadas externas, custom, sem span) e os spans que mais cresceram, com evidence.`,
+        '3. tracker_get_trace { projectId, traceId: <evidence do span que mais cresceu>, name: <nome do span> } — confirme no waterfall.',
+        `4. (se a decomposição vier null: um lado sem spans brutos) tracker_get_endpoint { projectId: ${p(args)}, name: ${name}, from: <deploy>${envArg(args)} } e tracker_get_trace do mais lento.`,
+        `5. (se precisar) tracker_endpoint_history { projectId: ${p(args)}, name: ${name}, days: 7${envArg(args)} } — a piora começou no deploy (markers) e continua no ponto mais recente?`,
+        '',
+        'Pare quando: tracker_compare mostrar o tipo de span ou o span que explica a maior parte do aumento de p95 e um trace da evidence confirmar; ou quando as 6 chamadas acabarem — então liste o que falta.',
+        'Cuidado: com coverage "none" em um lado, não há decomposição — não conclua regressão por tipo de span sem cobertura.',
+        '',
+        ...COMMON_RULES,
+    ].join('\n');
+}
+export function slowQueryPrompt(args) {
+    return [
+        ...header('Investigar query lenta ou N+1', args),
+        'Objetivo: achar a query que mais custa, dizer se é uma execução lenta (p99/máximo), repetição (N+1) ou espera de lock, e quem a chama.',
+        '',
+        'Sequência:',
+        args.env ? '' : `1. tracker_list_environments { projectId: ${p(args)} } — escolha o ambiente (produção) se houver mais de um.`,
+        `${args.env ? '1' : '2'}. tracker_list_queries { projectId: ${p(args)}, range: "24h"${envArg(args)}${args.query ? `, search: "${args.query}"` : ''} } — top por tempo total, p95/p99/máximo, chamadores e evidence (trace e span da execução mais lenta).`,
+        `${args.env ? '2' : '3'}. tracker_get_trace { projectId, traceId: <evidence[0].traceId>, kind: "db.query" } — veja se a query aparece repetida (summary.repeated, evidence repeated.count) ou uma vez lenta.`,
+        `${args.env ? '3' : '4'}. (se repetida) tracker_list_issues { projectId, type: ["N_PLUS_ONE", "LOOP"], q: <trecho da query> } — a issue já detectada, com contagem e commits suspeitos via tracker_get_issue.`,
+        '',
+        'Classifique: nome com pg_advisory_lock/FOR UPDATE/LOCK = espera de lock (o tempo é de outra transação); repeated.count alto = N+1 (agrupe numa consulta); p99/máximo muito acima do p95 = outliers (procure o parâmetro no trace).',
+        'Pare quando: a query, o chamador e um trace com o span (traceId + spanId) estiverem identificados e classificados.',
+        'Limite atual: o SDK corta o SQL em 200 caracteres; duas queries com o mesmo início aparecem juntas.',
+        '',
+        ...COMMON_RULES,
+    ]
+        .filter((line) => line !== '')
+        .join('\n');
+}
+export function lateJobPrompt(args) {
+    const monitor = args.monitor ? `slug: "${args.monitor}"` : 'monitorId: <id do monitor missed/down>';
+    return [
+        ...header('Investigar job atrasado ou que não rodou', args),
+        'Objetivo: dizer se o job rodou, quando devia ter rodado, quanto atrasou, por que falhou e se alguém foi alertado.',
+        '',
+        'Sequência:',
+        `1. tracker_list_monitors { projectId: ${p(args)}${envArg(args, 'environment')} } — status (missed/down), último check e próximo prazo.`,
+        `2. tracker_get_monitor { projectId: ${p(args)}, ${monitor}${envArg(args, 'environment')} } — checks com traceId, horário esperado e atraso de cada execução (delayMs), schedule.overdueMs (quanto já passou do prazo) e runningSince (execução ainda aberta). evidence traz os checks que falharam.`,
+        '3. tracker_get_trace { projectId, traceId: <evidence[0].traceId> } — onde a execução falhou ou demorou.',
+        '4. tracker_search_logs { projectId, traceId: <o mesmo> } — erros da execução.',
+        `5. tracker_list_alert_events { projectId: ${p(args)}, type: ["monitor_down"] } — se e quando o alerta disparou e se a entrega saiu.`,
+        '',
+        'Pare quando: houver o check que falhou ou faltou (com o trace, se o job reporta trace), a causa no trace/log e o estado do alerta.',
+        'Cuidado: um job longo ainda em execução pode aparecer como missed; confira runningSince antes de concluir que não rodou.',
+        '',
+        ...COMMON_RULES,
+    ].join('\n');
+}
+export function distributedErrorPrompt(args) {
+    return [
+        ...header('Investigar erro distribuído (API → serviços)', args),
+        'Objetivo: a partir de requisições com erro, achar o serviço e o span onde a falha começou e o log ou a issue que a explica.',
+        '',
+        'Sequência:',
+        `1. tracker_list_traces { projectId: ${p(args)}, rootKind: "all", hasSpan: { status: "error" }, sort: "duration", range: "24h"${envArg(args)}${args.endpoint ? `, endpoint: "${args.endpoint}"` : ''} } — traces com algum span com erro (inclusive filhos e outros serviços), mais lentos primeiro. Use hasSpan.service para ficar num serviço.`,
+        '2. tracker_get_trace { projectId, traceId: <um deles> } — `services` mostra os serviços do trace; evidence traz os spans que falharam (statusCode/error) com o serviço.',
+        '3. tracker_search_logs { projectId, traceId: <o mesmo> } — logs de todos os serviços do trace.',
+        '4. tracker_list_issues { projectId, type: ["ERROR"], q: <mensagem ou nome do span> } e, se preciso, tracker_get_issue — impacto, releases e commits suspeitos.',
+        '',
+        'Pare quando: o primeiro span com erro (o mais profundo/antigo) estiver identificado com serviço, mensagem e um log ou issue que confirme.',
+        'Limite atual: erros do navegador ainda não se ligam ao trace da API (o SDK de navegador cria um trace próprio); esta jornada cobre API → serviços.',
+        '',
+        ...COMMON_RULES,
+    ].join('\n');
+}
+export function confirmFixPrompt(args) {
+    const name = args.endpoint ? `"${args.endpoint}"` : '<rota ou job corrigido>';
+    const since = args.deployedAt ? `"${args.deployedAt}"` : '<instante do deploy, ISO>';
+    return [
+        ...header('Confirmar que uma correção funcionou', args),
+        'Objetivo: comparar antes e depois do deploy da correção e dizer, com evidência, se o problema parou.',
+        '',
+        'Sequência:',
+        `1. tracker_list_releases { projectId: ${p(args)}${envArg(args, 'environment')}${args.release ? `, version: "${args.release}"` : ''} } — saúde da release nova contra a anterior (p95, erro, issues novas, regressões).`,
+        `2. tracker_compare { projectId: ${p(args)}, a: { from: <deploy − mesma duração>, to: ${since} }, b: { from: ${since} }${args.endpoint ? `, endpoint: "${args.endpoint}"` : ''}${envArg(args)} } — antes × depois: p95, erro e onde o tempo mudou, com traces de prova (ou tracker_get_endpoint { name: ${name}, from: ${since} } para só a rota).`,
+        `3. tracker_log_stats { projectId: ${p(args)}, from: <deploy − mesma duração>, to: <agora>, level: "error"${envArg(args)} } — quando os erros pararam (último bucket com erro antes ou depois de ${since}).`,
+        `4. tracker_list_alert_events { projectId: ${p(args)}, from: ${since} } — nenhum alerta novo do tipo, ou o episódio resolvido.`,
+        '5. (se havia issue) tracker_get_issue { projectId, issueId } — a última ocorrência é anterior ao deploy?',
+        '',
+        'Pare quando: as janelas depois do deploy mostram o alvo atingido (p95/erro), sem alerta novo, com evidência de um trace recente bom; ou quando uma delas mostrar que o problema continua (aí cite o trace ruim recente).',
+        '',
+        ...COMMON_RULES,
+    ].join('\n');
+}
+const optional = (description) => z.string().max(512).optional().describe(description);
+export const JOURNEYS = [
+    { name: 'investigar-regressao-p95', title: 'Investigar regressão de p95 após um deploy', build: regressionPrompt, args: { projectId: optional('ID do projeto'), endpoint: optional('Rota suspeita (opcional)'), release: optional('Versão do deploy (opcional)'), env: optional('Ambiente, ex.: production') } },
+    { name: 'investigar-query-lenta', title: 'Investigar query lenta ou N+1', build: slowQueryPrompt, args: { projectId: optional('ID do projeto'), query: optional('Trecho do SQL (opcional)'), env: optional('Ambiente, ex.: production') } },
+    { name: 'investigar-job-atrasado', title: 'Investigar job atrasado ou que não rodou', build: lateJobPrompt, args: { projectId: optional('ID do projeto'), monitor: optional('Slug do monitor (opcional)'), env: optional('Ambiente, ex.: production') } },
+    { name: 'investigar-erro-distribuido', title: 'Investigar erro distribuído (API → serviços)', build: distributedErrorPrompt, args: { projectId: optional('ID do projeto'), endpoint: optional('Rota ou job com erro (opcional)'), env: optional('Ambiente, ex.: production') } },
+    { name: 'confirmar-correcao', title: 'Confirmar que uma correção funcionou', build: confirmFixPrompt, args: { projectId: optional('ID do projeto'), endpoint: optional('Rota ou job corrigido'), release: optional('Versão com a correção'), deployedAt: optional('Instante do deploy (ISO 8601)'), env: optional('Ambiente, ex.: production') } },
+];
+export function registerJourneyPrompts(server) {
+    for (const journey of JOURNEYS) {
+        server.registerPrompt(journey.name, { title: journey.title, description: `${journey.title}: sequência de ferramentas (até 6 chamadas), critério de parada e evidência exigida.`, argsSchema: journey.args }, (args) => ({ messages: [{ role: 'user', content: { type: 'text', text: journey.build(args) } }] }));
+    }
+}
+//# sourceMappingURL=journeys.js.map

package/dist/journeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journeys.js","sourceRoot":"","sources":["../src/journeys.ts"],"names":[],"mappings":"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"}

package/dist/links.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Janelas, evidências e links das ferramentas de diagnóstico (docs/mcp.md, "Evidências e links").
+ *
+ * - `evidence[]` aponta só para traces que a API devolveu nesta chamada: o agente pode abrir
+ *   cada um (tracker_get_trace ou o recurso fg-tracker://trace/{traceId}) e conferir o número.
+ * - Links do painel só saem quando a URL do painel é conhecida (FG_TRACKER_WEB_URL ou derivada
+ *   da API); senão `dashboard: null`.
+ */
+import { type QueryValue, type RangeKey, type TrackClient } from './client.js';
+import { type ResourceLink } from './format.js';
+import type { Evidence } from './schemas.js';
+export interface Window {
+    from: string;
+    to: string;
+}
+export interface Links {
+    dashboard: string | null;
+    resource?: string;
+}
+/**
+ * Templates dos recursos. `?projectId=` é um sufixo opcional (os links que o servidor gera
+ * sempre o trazem); sem ele, a leitura procura o id nos projetos acessíveis.
+ */
+export declare const TRACE_URI_TEMPLATE = "fg-tracker://trace/{traceId}";
+export declare const ISSUE_URI_TEMPLATE = "fg-tracker://issue/{issueId}";
+/** Id e `projectId` opcional de `fg-tracker://<tipo>/<id>[?projectId=…]`. */
+export declare function parseResourceUri(uri: URL): {
+    id: string;
+    projectId: string | undefined;
+};
+export declare function traceUri(projectId: string, traceId: string): string;
+export declare function issueUri(projectId: string, issueId: string): string;
+/** Janela `[agora − range, agora]` como a API calcula. */
+export declare function rangeWindow(range: RangeKey, now?: number): Window;
+/** Maior janela absoluta aceita pela API de logs (`logs-query.service.ts`, 31 dias). */
+export declare const LOGS_MAX_WINDOW_DAYS = 31;
+/**
+ * Janela de uma consulta com `from`/`to` opcionais, como a API de logs calcula: sem os dois,
+ * `[agora − range, agora]`; só `to`, a janela `range` que termina em `to`; só `from`, de `from`
+ * até agora. Validada aqui para o erro sair antes da chamada.
+ */
+export declare function resolveWindow(range: RangeKey, from?: string, to?: string, maxDays?: number | null, now?: number): Window;
+export interface WindowedResult<T> {
+    body: T;
+    window: Window;
+    /** from/to pedidos e a API não confirmou (API anterior à janela absoluta): os números são do `range`. */
+    windowIgnored: boolean;
+    /** Parâmetros extras que a API declarou ter aplicado (`x-fg-tracker-capabilities`). */
+    capabilities: Set<string>;
+}
+export declare const WINDOW_IGNORED_NOTE = "ATEN\u00C7\u00C3O: esta API ignorou from/to (vers\u00E3o anterior \u00E0 janela absoluta); os n\u00FAmeros s\u00E3o do range relativo.";
+/**
+ * GET de uma leitura de métricas com `range` ou `from`/`to` (validados aqui, até 31 dias). A
+ * janela devolvida é a que a API confirmou no cabeçalho; sem a confirmação, `windowIgnored`.
+ */
+export declare function getWithWindow<T>(client: TrackClient, path: string, query: Record<string, QueryValue>, range: RangeKey, from?: string, to?: string): Promise<WindowedResult<T>>;
+/** Intervalo de um span ou trace: `[startedAt, startedAt + durationMs]`. */
+export declare function spanWindow(startedAt: string, durationMs: number): Window;
+/** Página do painel (`/trace/?project=…&trace=…`), ou `null` sem URL do painel. */
+export declare function dashboardUrl(client: TrackClient, page: string, params: Record<string, string>): string | null;
+export declare function traceLinks(client: TrackClient, projectId: string, traceId: string): {
+    links: Links;
+    resourceLinks: ResourceLink[];
+};
+export declare function issueLinks(client: TrackClient, projectId: string, issueId: string): {
+    links: Links;
+    resourceLinks: ResourceLink[];
+};
+export declare function pageLinks(client: TrackClient, page: string, params: Record<string, string>, name: string): {
+    links: Links;
+    resourceLinks: ResourceLink[];
+};
+/** Links `fg-tracker://trace/…` das evidências (sem repetir trace), até `max`. */
+export declare function evidenceResourceLinks(projectId: string, evidence: Evidence[], max?: number): ResourceLink[];
+interface TraceLike {
+    traceId: string;
+    startedAt: string;
+    durationMs: number;
+    name?: string;
+    statusCode?: number | null;
+}
+export declare function traceEvidence(item: TraceLike, metric?: string, value?: number | string, note?: string): Evidence;
+/** Os `max` traces mais lentos de uma lista, como evidência de duração. */
+export declare function tracesEvidence(items: TraceLike[], max?: number): Evidence[];
+/** Resumo em texto das evidências, para clientes que só mostram o `content`. */
+export declare function evidenceLines(evidence: Evidence[], max?: number): string;
+export {};

package/dist/links.js

@@ -0,0 +1,124 @@
+/**
+ * Janelas, evidências e links das ferramentas de diagnóstico (docs/mcp.md, "Evidências e links").
+ *
+ * - `evidence[]` aponta só para traces que a API devolveu nesta chamada: o agente pode abrir
+ *   cada um (tracker_get_trace ou o recurso fg-tracker://trace/{traceId}) e conferir o número.
+ * - Links do painel só saem quando a URL do painel é conhecida (FG_TRACKER_WEB_URL ou derivada
+ *   da API); senão `dashboard: null`.
+ */
+import { RANGE_SECONDS } from './client.js';
+import { ms } from './format.js';
+/**
+ * Templates dos recursos. `?projectId=` é um sufixo opcional (os links que o servidor gera
+ * sempre o trazem); sem ele, a leitura procura o id nos projetos acessíveis.
+ */
+export const TRACE_URI_TEMPLATE = 'fg-tracker://trace/{traceId}';
+export const ISSUE_URI_TEMPLATE = 'fg-tracker://issue/{issueId}';
+/** Id e `projectId` opcional de `fg-tracker://<tipo>/<id>[?projectId=…]`. */
+export function parseResourceUri(uri) {
+    return { id: decodeURIComponent(uri.pathname.replace(/^\/+/, '')), projectId: uri.searchParams.get('projectId') ?? undefined };
+}
+export function traceUri(projectId, traceId) {
+    return `fg-tracker://trace/${encodeURIComponent(traceId)}?projectId=${encodeURIComponent(projectId)}`;
+}
+export function issueUri(projectId, issueId) {
+    return `fg-tracker://issue/${encodeURIComponent(issueId)}?projectId=${encodeURIComponent(projectId)}`;
+}
+/** Janela `[agora − range, agora]` como a API calcula. */
+export function rangeWindow(range, now = Date.now()) {
+    return { from: new Date(now - RANGE_SECONDS[range] * 1000).toISOString(), to: new Date(now).toISOString() };
+}
+/** Maior janela absoluta aceita pela API de logs (`logs-query.service.ts`, 31 dias). */
+export const LOGS_MAX_WINDOW_DAYS = 31;
+/**
+ * Janela de uma consulta com `from`/`to` opcionais, como a API de logs calcula: sem os dois,
+ * `[agora − range, agora]`; só `to`, a janela `range` que termina em `to`; só `from`, de `from`
+ * até agora. Validada aqui para o erro sair antes da chamada.
+ */
+export function resolveWindow(range, from, to, maxDays = LOGS_MAX_WINDOW_DAYS, now = Date.now()) {
+    if (!from && !to)
+        return rangeWindow(range, now);
+    const end = to ? Date.parse(to) : now;
+    const start = from ? Date.parse(from) : end - RANGE_SECONDS[range] * 1000;
+    if (end <= start)
+        throw new Error(`\`to\` (${to ?? 'agora'}) precisa ser depois de \`from\` (${from}).`);
+    if (maxDays !== null && end - start > maxDays * 86_400_000)
+        throw new Error(`Janela de ${Math.ceil((end - start) / 86_400_000)} dias: o máximo é ${maxDays}. Encurte from/to.`);
+    return { from: new Date(start).toISOString(), to: new Date(end).toISOString() };
+}
+export const WINDOW_IGNORED_NOTE = 'ATENÇÃO: esta API ignorou from/to (versão anterior à janela absoluta); os números são do range relativo.';
+/**
+ * GET de uma leitura de métricas com `range` ou `from`/`to` (validados aqui, até 31 dias). A
+ * janela devolvida é a que a API confirmou no cabeçalho; sem a confirmação, `windowIgnored`.
+ */
+export async function getWithWindow(client, path, query, range, from, to) {
+    const absolute = Boolean(from || to);
+    const requested = resolveWindow(range, from, to);
+    const res = await client.getWindowed(path, { ...query, range, ...(absolute ? requested : {}) });
+    if (!absolute)
+        return { body: res.body, window: requested, windowIgnored: false, capabilities: res.capabilities };
+    return { body: res.body, window: res.window ?? rangeWindow(range), windowIgnored: res.window === null, capabilities: res.capabilities };
+}
+/** Intervalo de um span ou trace: `[startedAt, startedAt + durationMs]`. */
+export function spanWindow(startedAt, durationMs) {
+    const start = Date.parse(startedAt);
+    if (Number.isNaN(start))
+        return { from: startedAt, to: startedAt };
+    return { from: new Date(start).toISOString(), to: new Date(start + Math.max(0, durationMs)).toISOString() };
+}
+/** Página do painel (`/trace/?project=…&trace=…`), ou `null` sem URL do painel. */
+export function dashboardUrl(client, page, params) {
+    const web = client.webUrl;
+    if (!web)
+        return null;
+    const query = new URLSearchParams(params).toString();
+    return `${web}/${page}/${query ? `?${query}` : ''}`;
+}
+function resourceLinks(links, name, description) {
+    const out = [];
+    if (links.dashboard)
+        out.push({ type: 'resource_link', uri: links.dashboard, name: `${name} (painel)`, description: `${description} no painel do FG Tracker`, mimeType: 'text/html' });
+    if (links.resource)
+        out.push({ type: 'resource_link', uri: links.resource, name, description: `${description} (JSON, resources/read)`, mimeType: 'application/json' });
+    return out;
+}
+export function traceLinks(client, projectId, traceId) {
+    const links = { dashboard: dashboardUrl(client, 'trace', { project: projectId, trace: traceId }), resource: traceUri(projectId, traceId) };
+    return { links, resourceLinks: resourceLinks(links, `trace ${traceId}`, 'Waterfall do trace') };
+}
+export function issueLinks(client, projectId, issueId) {
+    const links = { dashboard: dashboardUrl(client, 'issue', { project: projectId, issue: issueId }), resource: issueUri(projectId, issueId) };
+    return { links, resourceLinks: resourceLinks(links, `issue ${issueId}`, 'Issue') };
+}
+export function pageLinks(client, page, params, name) {
+    const links = { dashboard: dashboardUrl(client, page, params) };
+    return { links, resourceLinks: resourceLinks(links, name, name) };
+}
+/** Links `fg-tracker://trace/…` das evidências (sem repetir trace), até `max`. */
+export function evidenceResourceLinks(projectId, evidence, max = 3) {
+    const seen = new Set();
+    const out = [];
+    for (const item of evidence) {
+        if (seen.has(item.traceId) || out.length >= max)
+            continue;
+        seen.add(item.traceId);
+        out.push({ type: 'resource_link', uri: traceUri(projectId, item.traceId), name: `trace ${item.traceId}`, description: `Evidência: ${item.metric} = ${item.value}`, mimeType: 'application/json' });
+    }
+    return out;
+}
+export function traceEvidence(item, metric = 'durationMs', value = item.durationMs, note) {
+    const label = note ?? item.name;
+    return { traceId: item.traceId, metric, value, window: spanWindow(item.startedAt, item.durationMs), ...(label ? { note: label } : {}) };
+}
+/** Os `max` traces mais lentos de uma lista, como evidência de duração. */
+export function tracesEvidence(items, max = 5) {
+    return [...items].sort((a, b) => b.durationMs - a.durationMs).slice(0, max).map((item) => traceEvidence(item));
+}
+/** Resumo em texto das evidências, para clientes que só mostram o `content`. */
+export function evidenceLines(evidence, max = 5) {
+    if (!evidence.length)
+        return '';
+    const fmt = (e) => (typeof e.value === 'number' && /ms$/i.test(e.metric) ? ms(e.value) : String(e.value));
+    return `\nEvidência: ${evidence.slice(0, max).map((e) => `trace ${e.traceId}${e.spanId ? ` span ${e.spanId}` : ''} (${e.metric} ${fmt(e)})`).join('; ')}${evidence.length > max ? ` (+${evidence.length - max})` : ''}`;
+}
+//# sourceMappingURL=links.js.map

package/dist/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../src/links.ts"],"names":[],"mappings":"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"}

package/dist/loadtest/tools.js

@@ -6,7 +6,8 @@ import { stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { z } from 'zod';
 import { TrackApiError } from '../client.js';
-import { guard, json, text } from '../format.js';
+import { guard, json, structured, text } from '../format.js';
+import { planOutput, routesOutput, scenariosOutput } from '../schemas.js';
 import { formatRouteScan, scanRoutes } from './routes.js';
 import { PRESETS, describePlan, planWarnings, presetPlan, validatePlan, validateScenario, } from './scenario.js';
 const projectIdSchema = z.string().uuid().describe('ID (uuid) do projeto — veja tracker_list_projects');
@@ -210,10 +211,14 @@ export function registerLoadtestTools(server, client) {
             path: z.string().optional().describe('Diretório do app/serviço (default: diretório atual)'),
             format: z.enum(['text', 'json']).default('text').describe('text (compacto) ou json (estrutura completa)'),
         },
+        outputSchema: routesOutput,
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ path, format }) => guard(async () => {
         const scan = await scanRoutes(await resolveRoot(path));
-        return format === 'json' ? json(scan) : text(formatRouteScan(scan));
+        if (format === 'json')
+            return { ...json(scan), structuredContent: { format, scan } };
+        const report = formatRouteScan(scan);
+        return structured({ format, report }, report, { body: null });
     }));
     server.registerTool('loadtest_create_scenario', {
         title: 'Criar roteiro de simulação (jornada)',
@@ -269,16 +274,19 @@ export function registerLoadtestTools(server, client) {
         title: 'Listar roteiros de simulação',
         description: 'GET /v1/projects/:id/loadtest/scenarios: id, nome, origem (mcp|editor), passos e atualização.',
         inputSchema: { projectId: projectIdSchema },
+        outputSchema: scenariosOutput,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async ({ projectId }) => guard(async () => {
         const list = asList(await client.get(`${base(projectId)}/scenarios`));
         if (list.length === 0)
-            return text('Nenhum roteiro. Crie um com o prompt create-load-test ou `loadtest_create_scenario`.');
+            return structured({ total: 0, items: [] }, 'Nenhum roteiro. Crie um com o prompt create-load-test ou `loadtest_create_scenario`.', { body: null });
         const lines = list.map((s) => {
             const doc = s.document;
             return `- ${String(s.name ?? '?')} · id ${String(s.id ?? '?')} · ${String(s.source ?? '?')}${doc?.steps ? ` · ${doc.setup?.length ?? 0} setup + ${doc.steps.length} passos` : ''}${s.updatedAt ? ` · atualizado ${String(s.updatedAt)}` : ''}`;
         });
-        return text(`${list.length} roteiro(s):\n${lines.join('\n')}`);
+        // O documento inteiro fica de fora: o resumo de passos basta para escolher o roteiro.
+        const items = list.map(({ document, ...rest }) => ({ ...rest, steps: document?.steps?.length ?? null }));
+        return structured({ total: list.length, items }, `${list.length} roteiro(s):\n${lines.join('\n')}`, { body: null });
     }));
     server.registerTool('loadtest_suggest_plan', {
         title: 'Sugerir plano de carga (preset k6)',
@@ -289,12 +297,13 @@ export function registerLoadtestTools(server, client) {
             targetRps: z.number().positive().optional().describe('Alvo de iterações por segundo (usa arrival-rate)'),
             duration: z.string().optional().describe('Duração total no formato k6 ("10m", "2h")'),
         },
+        outputSchema: planOutput,
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async ({ preset, vus, targetRps, duration }) => guard(async () => {
         const plan = presetPlan(preset, { vus, targetRps, duration });
         const shape = describePlan(plan);
         const warnings = planWarnings(plan);
-        return json(plan, [`Plano ${preset}: ${shape.executor} · pico ${shape.peakVus} VUs${shape.peakIterationsPerSecond !== null ? ` / ${shape.peakIterationsPerSecond} it/s` : ''} · ${shape.duration}.`, ...warnings.map((w) => `Atenção: ${w}`), 'Ajuste thresholds ao SLO do produto. Na UI, "Avaliar com IA" confere o plano contra os limites da conta.'].join('\n'));
+        return structured({ preset, plan: plan, warnings }, [`Plano ${preset}: ${shape.executor} · pico ${shape.peakVus} VUs${shape.peakIterationsPerSecond !== null ? ` / ${shape.peakIterationsPerSecond} it/s` : ''} · ${shape.duration}.`, ...warnings.map((w) => `Atenção: ${w}`), 'Ajuste thresholds ao SLO do produto. Na UI, "Avaliar com IA" confere o plano contra os limites da conta.'].join('\n'), { body: plan });
     }));
     server.registerTool('loadtest_get_run', {
         title: 'Resultado de uma simulação',