get_audit

O que esta ferramenta faz

get_audit devolve o resultado completo de uma auditoria executada anteriormente pelo seu audit_id. É o alvo de polling de run_audit e a forma canónica de ler cada descoberta para um dado URL.

• Devolve o mesmo envelope McpAuditResponse que run_audit, mas com as descobertas preenchidas assim que a auditoria termina.
• Expõe pontuações de módulo (0-100) em todos os 11 módulos de auditoria, mais o total_score agregado.
• Inclui cada descoberta com module, rule_id, passed, severity, title, recommendation opcional, e um docs_url.
• Devolve status a refletir o estado upstream: queued, running, complete, ou failed.
• Fornece um deep-link report_url para o relatório HTML em app.metricspot.com.

Por que importa

get_audit é o lado de leitura do servidor MCP. Os agentes chamam-no para fazer polling a uma execução em fila, para reler descobertas de uma auditoria anterior, ou para comparar duas auditorias do mesmo URL ao longo do tempo.

Fluxos concretos:

• Um bot de comentários de PR chama get_audit para a auditoria anterior de um URL, faz diff do total_score contra o novo, e só escala quando a regressão ultrapassa um limiar.
• Um agente “corrige uma descoberta de cada vez” itera as findings filtradas por severity: critical, abre um issue por cada regra que falha, e liga o docs_url para contexto.

Como usá-la

Passa o audit_id devolvido por run_audit (ou por list_audits). O mesmo id pode ser consultado repetidamente; os resultados são cacheados no servidor e baratos de ler.

Schema de entrada

{
  "type": "object",
  "properties": {
    "audit_id": { "type": "string", "minLength": 1 }
  },
  "required": ["audit_id"]
}

Amostra do schema de resposta

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "url": "https://example.com",
  "status": "complete",
  "total_score": 82,
  "module_scores": {
    "technical": 95,
    "onpage": 76,
    "performance": 71,
    "ai": 84,
    "modern_seo": 80,
    "social": 65,
    "accessibility": 90,
    "privacy": 78,
    "readability": 85,
    "tech_stack": 100
  },
  "findings": [
    {
      "module": "technical",
      "rule_id": "technical.https",
      "passed": true,
      "severity": "critical",
      "title": "Site is served over HTTPS",
      "docs_url": "https://metricspot.com/docs/technical-https/"
    },
    {
      "module": "ai",
      "rule_id": "ai.llms_txt",
      "passed": false,
      "severity": "minor",
      "title": "No llms.txt published",
      "recommendation": "Add an llms.txt to /.well-known/ listing canonical docs URLs for LLM crawlers.",
      "docs_url": "https://metricspot.com/docs/llms-txt/"
    }
  ],
  "report_url": "https://app.metricspot.com/audits/aud_01HZ8X9YP7K3T2N6Q5",
  "created_at": "2026-05-13T10:18:04.000Z"
}

Claude Code

claude mcp add --transport http metricspot https://mcp.metricspot.com/mcp \
  --header "Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Pede:

Vai buscar a auditoria MetricSpot aud_01HZ8X9YP7K3T2N6Q5 e lista cada descoberta que falhou agrupada por módulo, ordenada por gravidade.

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "metricspot": {
      "url": "https://mcp.metricspot.com/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Pede:

Vai buscar a última auditoria deste URL ao MetricSpot e reescreve o título da página para corrigir as regras on-page que falham.

Python (polling até concluir)

import httpx, time, json

HEADERS = {
    "content-type": "application/json",
    "accept": "application/json, text/event-stream",
    "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
}

def get_audit(audit_id):
    r = httpx.post("https://mcp.metricspot.com/mcp", headers=HEADERS, json={
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": "get_audit", "arguments": {"audit_id": audit_id}},
    }, timeout=60.0)
    return json.loads(r.json()["result"]["content"][0]["text"])

while True:
    audit = get_audit("aud_01HZ8X9YP7K3T2N6Q5")
    if audit["status"] in ("complete", "failed"):
        break
    time.sleep(3)

print("score:", audit["total_score"])
for f in audit["findings"]:
    if not f["passed"] and f["severity"] in ("critical", "major"):
        print(f["severity"], f["rule_id"], "-", f["title"])

Node / TypeScript (HTTP direto)

const res = await fetch("https://mcp.metricspot.com/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "get_audit",
      arguments: { audit_id: "aud_01HZ8X9YP7K3T2N6Q5" },
    },
  }),
});
const audit = JSON.parse((await res.json()).result.content[0].text);
console.log(audit.status, audit.total_score);

Erros comuns

Código	Quando	Ação
UNAUTHORIZED (401)	Token Bearer em falta ou inválido	Emite uma chave em https://app.metricspot.com/settings/api-keys
AUDIT_NOT_FOUND (404)	audit_id não pertence a esta conta	Chama list_audits para ids válidos
FORBIDDEN (403)	Token sem scope de leitura	Reemite a chave com o scope padrão
UPSTREAM_FAILED (5xx)	Erro no backend da app	Tenta de novo; retryable: true está definido em falhas transitórias

Perguntas frequentes

Com que frequência devo fazer polling a uma auditoria em fila?

De 3 em 3 ou 5 em 5 segundos é o ponto certo. A maior parte das auditorias termina em 10-30 s, por isso 6-10 polls por auditoria é o típico. Não há custo por chamada além da rede. Faz backoff se o status permanecer queued durante mais de 90 s.

Posso ir buscar uma auditoria que outra pessoa executou?

Não. A pesquisa de auditoria está limitada ao dono da chave API. Chamar get_audit com o audit_id de outro utilizador devolve AUDIT_NOT_FOUND em vez de revelar que a auditoria existe. As auditorias anónimas (id "anonymous") não podem ser obtidas de todo.

A resposta inclui descobertas para regras que passaram?

Sim. Cada regra que o motor avaliou está em findings, com passed: true ou passed: false. Filtra no cliente para expor apenas falhas, ou para calcular taxas de aprovação por módulo.