fg-tracker-mcp

Servidor MCP (stdio) do FG Tracker para agentes de código (Claude Code, Cursor, Windsurf, Claude Desktop): projetos, métricas, traces, issues com commits suspeitos, releases, monitores, provedores externos, logs e guia de instrumentação. Documentação completa: docs/mcp.md no repositório.

Instalação

Claude Code:

claude mcp add fg-tracker \
  -e FG_TRACKER_URL=http://localhost:4050 \
  -e FG_TRACKER_TOKEN=<token-de-sessao> \
  -- npx -y fg-tracker-mcp

Cursor / Windsurf / Claude Desktop (JSON):

{
  "mcpServers": {
    "fg-tracker": {
      "command": "npx",
      "args": ["-y", "fg-tracker-mcp"],
      "env": {
        "FG_TRACKER_URL": "http://localhost:4050",
        "FG_TRACKER_TOKEN": "<token-de-sessao>"
      }
    }
  }
}

Em produção, FG_TRACKER_URL é a URL da API mostrada no painel em Conectar. O endereço de produção da API é https://tracker-api.fortground.com.br (o antigo track-api.fortground.com.br continua respondendo).

Variáveis de ambiente

| variável | default | uso | |---|---|---| | FG_TRACKER_URL | http://localhost:4050 | URL base da API | | FG_TRACKER_TOKEN | — | token de sessão (Authorization: Bearer) — projetos, métricas, traces, issues, logs | | FG_TRACKER_API_KEY | — | chave de projeto (x-fg-tracker-key) — opcional, só ingestão | | FG_TRACKER_TIMEOUT_MS | 15000 | timeout das chamadas HTTP |

Os nomes antigos STREAD_TRACK_* continuam lidos quando o nome novo está ausente.

Tools, prompt e resource

Tools track_* (nomes inalterados), prompt instrument-project e resource fg-tracker://docs/quickstart.

Infraestrutura AWS (0.6.0): tools infra_* e prompt connect-infrastructure — detectar contas/ambientes/regiões nas credenciais locais, conectar cada ambiente, descobrir recursos com credenciais locais (somente leitura), analisar o IaC, instrumentar, validar e gerar o PR de transferência de controle. Nenhuma tool altera recursos na AWS. Detalhes em docs/mcp.md → Infraestrutura.

Domínios permitidos (0.9.0): track_update_allowed_origins { projectId, origins } substitui as origens de navegador aceitas no CORS da ingestão (PATCH /v1/projects/:id { allowedOrigins }); track_list_projects mostra a lista atual — leia antes e confirme com o usuário.

Simulação de ambiente (0.8.0): prompt create-load-test e tools loadtest_* (CONTRATO.md §28.8):

| tool | entrada | o que faz | |---|---|---| | loadtest_scan_routes | { path?, format? } | local, somente leitura: rotas NestJS/Express/Next.js (método, caminho, arquivo:linha, controller, DTO, protegida?) e pistas de autenticação | | loadtest_create_scenario | { projectId, scenario, description? } | valida o roteiro (§28.2, erros com caminho do campo) e grava (POST /v1/projects/:id/loadtest/scenarios, ou POST /v1/loadtest/scenarios só com FG_TRACKER_API_KEY); resumo com passos, variáveis extraídas, checks e avisos de efeitos externos | | loadtest_list_scenarios | { projectId } | roteiros do projeto | | loadtest_suggest_plan | { preset, vus?, targetRps?, duration? } | puro: plano k6 (§28.3) para smoke/load/stress/spike/soak/breakpoint | | loadtest_get_run | { projectId, runId, generateAdvice? } | resumo do run: latências, erros, checks, thresholds, por passo e sugestões da IA | | loadtest_start_run | { projectId, scenarioId, baseUrl, connectionId, plan, credentialId?, environment?, confirm } | gera carga real: recusa sem confirm: true e devolve o texto de confirmação (ambiente, baseUrl, pico de VUs/RPS, duração); prefira iniciar pela UI |

Migração de stread-track-mcp

O pacote foi renomeado de stread-track-mcp (última versão no npm: 0.2.0) para fg-tracker-mcp (0.4.0). Nomes antigos continuam funcionando e serão removidos na 1.0.

| antigo | novo | compatibilidade | |---|---|---| | pacote stread-track-mcp | fg-tracker-mcp | as versões antigas seguem no npm | | bin stread-track-mcp | fg-tracker-mcp | o bin antigo é alias obsoleto (mesmo arquivo, aviso no stderr) | | STREAD_TRACK_URL, STREAD_TRACK_TOKEN, STREAD_TRACK_API_KEY, STREAD_TRACK_TIMEOUT_MS | FG_TRACKER_URL, FG_TRACKER_TOKEN, FG_TRACKER_API_KEY, FG_TRACKER_TIMEOUT_MS | o novo tem precedência; o antigo é fallback | | nome do servidor MCP stread-track | fg-tracker | renomeie a entrada na config do cliente quando quiser | | resource stread-track://docs/quickstart | fg-tracker://docs/quickstart | a URI antiga continua registrada (mesmo conteúdo) | | header x-stread-track-key | x-fg-tracker-key | a API aceita os dois | | tools track_*, prompt instrument-project | inalterados | — |

Na config do cliente: troque "stread-track": { "command": "npx", "args": ["-y", "stread-track-mcp"] } por "fg-tracker": { "command": "npx", "args": ["-y", "fg-tracker-mcp"] } e renomeie as variáveis de env.

Database detection (0.2.0)

track_detect_databases { projectPath, serviceName } inspects local Node project manifests and imports without opening .env/credential files, following symlinks, executing project scripts or reading dependencies. It returns candidate engines, driver adapters, source references and an implementation guide. Multiple databases are reported separately; a dependency alone is not proof of production use.

The coding agent must verify client creation sites, apply the appropriate SDK adapter, preserve transactions/pool settings, and validate real db.query spans under an HTTP request with track_get_trace. Detect before requesting track_instrumentation_guide { framework, databaseDriver, projectId }.

Native adapters: pg and Postgres.js (including Drizzle). Generic adapters cover synchronous, Promise and error-first callback operations; explicit completion wrappers cover other engines, ORM operations and cursor/stream consumption. Unknown drivers are not silently treated as pg. SQL is normalized and values are not exported. No double instrumentation at both ORM and driver layers.