get_audit

Cosa fa questo strumento

get_audit restituisce il risultato completo di un audit precedentemente eseguito tramite il suo audit_id. È il target di polling per run_audit e il modo canonico per leggere ogni finding di un dato URL.

• Restituisce lo stesso envelope McpAuditResponse di run_audit, ma con i finding popolati una volta che l’audit si completa.
• Espone i punteggi per modulo (0-100) su tutti gli 11 moduli di audit, più il total_score aggregato.
• Include ogni finding con module, rule_id, passed, severity, title, recommendation opzionale e un docs_url.
• Restituisce uno status che riflette lo stato upstream: queued, running, complete o failed.
• Fornisce un deep-link report_url al report HTML su app.metricspot.com.

Perché è importante

get_audit è il lato di lettura del server MCP. Gli agenti lo chiamano per fare polling su un run in coda, rileggere i finding di un audit precedente o confrontare due audit dello stesso URL nel tempo.

Workflow concreti:

• Un bot di commento PR chiama get_audit per l’audit precedente di un URL, fa il diff del total_score rispetto a quello nuovo e fa escalation solo quando la regressione supera una soglia.
• Un agente “fix di un finding alla volta” itera sui findings filtrati per severity: critical, apre una issue per ogni regola fallita e linka il docs_url per il contesto.

Come usarlo

Passa l’audit_id restituito da run_audit (o da list_audits). Lo stesso id può essere riconsultato ripetutamente; i risultati sono cachati lato server ed economici da leggere.

Schema di input

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

Esempio di schema di risposta

{
  "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"

Prompt:

Recupera l’audit MetricSpot aud_01HZ8X9YP7K3T2N6Q5 ed elenca ogni finding fallito raggruppato per modulo, ordinato per severity.

Cursor

.cursor/mcp.json:

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

Prompt:

Estrai l’ultimo audit per questo URL da MetricSpot e riscrivi il title della pagina per correggere ogni regola on-page fallita.

Python (polling fino al completamento)

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 grezzo)

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);

Errori comuni

Codice	Quando	Azione
UNAUTHORIZED (401)	Bearer token mancante o non valido	Genera una chiave su https://app.metricspot.com/settings/api-keys
AUDIT_NOT_FOUND (404)	audit_id non appartiene a questo account	Chiama list_audits per id validi
FORBIDDEN (403)	Il token non ha lo scope di lettura	Rigenera la chiave con lo scope di default
UPSTREAM_FAILED (5xx)	Errore del backend dell’app	Riprova; retryable: true è impostato sui fallimenti transitori

Domande frequenti

Ogni quanto dovrei fare polling su un audit in coda?

Ogni 3-5 secondi è il punto giusto. La maggior parte degli audit si completa in 10-30 s, quindi 6-10 polling per audit sono tipici. Non c’è costo per-chiamata oltre la rete. Fai backoff se status rimane queued per più di 90 s.

Posso recuperare un audit eseguito da qualcun altro?

No. La ricerca dell’audit è limitata al proprietario della API key. Chiamare get_audit con l’audit_id di un altro utente restituisce AUDIT_NOT_FOUND invece di rivelare che l’audit esiste. Gli audit anonimi (id "anonymous") non possono essere recuperati affatto.

La risposta include i finding per le regole passate?

Sì. Ogni regola valutata dal motore è in findings, con passed: true o passed: false. Filtra lato client per esporre solo i fallimenti, o per calcolare i tassi di passaggio per modulo.