get_audit - Docs de MetricSpot

Què fa aquesta eina

get_audit retorna el resultat complet d’una auditoria executada prèviament pel seu audit_id. És l’objectiu de poll per a run_audit i la manera canònica de llegir tots els findings d’una URL.

Retorna el mateix sobre McpAuditResponse que run_audit, però amb els findings omplerts un cop l’auditoria acaba.
Mostra puntuacions per mòdul (0-100) per a tots els 11 mòduls d’auditoria, més el total_score agregat.
Inclou cada finding amb module, rule_id, passed, severity, title, recommendation opcional i un docs_url.
Retorna status reflectint l’estat upstream: queued, running, complete o failed.
Proporciona un report_url que enllaça profundament amb l’informe HTML a app.metricspot.com.

Per què importa

get_audit és el costat de lectura del servidor MCP. Els agents la criden per fer poll d’una execució encuada, per rellegir findings d’una auditoria anterior o per comparar dues auditories de la mateixa URL al llarg del temps.

Fluxos concrets:

Un bot de comentaris a les PR crida get_audit per a l’auditoria anterior d’una URL, compara total_score amb la nova, i només escala quan la regressió supera un llindar.
Un agent “arregla un finding cada cop” recorre findings filtrats per severity: critical, obre una incidència per regla fallida i enllaça el docs_url com a context.

Com utilitzar-la

Passa l’audit_id retornat per run_audit (o per list_audits). El mateix id es pot consultar repetidament; els resultats es cachegen al servidor i són econòmics de llegir.

Esquema d’entrada

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

Mostra de l’esquema 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"

Prompt:

Fetch MetricSpot audit aud_01HZ8X9YP7K3T2N6Q5 and list every failed finding grouped by module, sorted by severity.

Cursor

.cursor/mcp.json:

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

Prompt:

Pull the last audit for this URL from MetricSpot and rewrite the page’s title to fix any failing on-page rules.

Python (poll fins a complete)

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 en cru)

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

Errors habituals

Codi	Quan	Acció
`UNAUTHORIZED` (401)	Token Bearer absent o invàlid	Emet una clau a `https://app.metricspot.com/settings/api-keys`
`AUDIT_NOT_FOUND` (404)	`audit_id` no pertany al teu compte	Crida `list_audits` per a ids vàlids
`FORBIDDEN` (403)	El token no té scope de lectura	Reemet la clau amb l’scope per defecte
`UPSTREAM_FAILED` (5xx)	Error de backend de l’app	Reintenta; es retorna `retryable: true` en errors transitoris

Preguntes freqüents

Amb quina freqüència he de fer poll d’una auditoria encuada?

Cada 3-5 segons és el punt dolç. La majoria d’auditories acaben en 10-30 s, així que 6-10 polls per auditoria és típic. No hi ha cost per crida més enllà de la xarxa. Fes backoff si status es queda en queued més de 90 s.

Puc obtenir una auditoria que ha executat algú altre?

No. La cerca d’auditoria està limitada al propietari de la clau d’API. Cridar get_audit amb l’audit_id d’un altre usuari retorna AUDIT_NOT_FOUND enlloc de filtrar que l’auditoria existeix. Les auditories anònimes (id "anonymous") no es poden obtenir en cap cas.

La resposta inclou findings per a les regles que han passat?

Sí. Cada regla que el motor ha avaluat és a findings, amb passed: true o passed: false. Filtra al client per mostrar només els errors, o per calcular ràtios d’èxit per mòdul.