get_audit_pdf - Docs de MetricSpot

Què fa aquesta eina

get_audit_pdf retorna una URL de descàrrega signada de l’informe PDF amb marca d’una auditoria donada. Si encara no s’ha renderitzat cap PDF, encua un render i retorna un estat queued.

Rep un audit_id (el mateix valor que ha retornat run_audit).
Retorna audit_id, pdf_url i status (ready o queued).
La URL signada té vida curta; tracta-la com a d’un sol ús i descarrega immediatament.
Si status: queued, torna a cridar l’eina al cap d’uns segons, o consulta la URL quan el render acabi.
La marca white-label (logo, nom d’empresa, tema) segueix el pla de l’usuari i la configuració del dashboard.

Per què importa

El PDF és el lliurable que la majoria de consultors i agències donen als clients. Deixar que un agent obtingui una URL signada vol dir que una sola crida MCP pot acabar un flux end-to-end “auditar i informar” que abans requeria una pestanya del dashboard.

Fluxos concrets:

Un agent “informe al client” executa run_audit, fa poll a get_audit, i llavors crida get_audit_pdf i adjunta la URL signada a un esborrany de correu.
Un agent “arxivar el darrer trimestre” recorre list_audits, obté cada PDF, i els desa a Drive o S3 amb la URL i el created_at com a nom de fitxer.

Com utilitzar-la

get_audit_pdf per sota és un POST: la primera crida dispara un render si la cache és freda. Si el PDF s’ha renderitzat recentment, la URL torna immediatament. Si no, preveu 5-15 s de temps de render; fes poll a l’eina cada pocs segons.

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",
  "pdf_url": "https://cdn.metricspot.com/reports/aud_01HZ8X9YP7K3T2N6Q5.pdf?signature=...",
  "status": "ready"
}

Quan el render encara està en curs:

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "pdf_url": "",
  "status": "queued"
}

Claude Code

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

Prompt:

Get the PDF for audit aud_01HZ8X9YP7K3T2N6Q5 from MetricSpot and give me the download link.

Cursor

.cursor/mcp.json:

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

Prompt:

Fetch the latest audit for example.com, wait for the PDF, and download it to ./reports.

Python (poll fins a estar llest i descarregar)

import httpx, time, json

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

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

for _ in range(10):
    pdf = call("get_audit_pdf", {"audit_id": "aud_01HZ8X9YP7K3T2N6Q5"})
    if pdf["status"] == "ready":
        break
    time.sleep(3)

with httpx.stream("GET", pdf["pdf_url"]) as r:
    with open("report.pdf", "wb") as f:
        for chunk in r.iter_bytes():
            f.write(chunk)

Node / TypeScript (HTTP en cru)

import { writeFile } from "node:fs/promises";

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_pdf",
      arguments: { audit_id: "aud_01HZ8X9YP7K3T2N6Q5" },
    },
  }),
});
const pdf = JSON.parse((await res.json()).result.content[0].text);
if (pdf.status === "ready") {
  const file = await fetch(pdf.pdf_url);
  await writeFile("report.pdf", Buffer.from(await file.arrayBuffer()));
}

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)	L’exportació de PDF requereix un pla de pagament en alguns comptes	Actualitza a `https://app.metricspot.com/billing`
`UPSTREAM_FAILED` (5xx)	Falla del servei de render	Reintenta un cop; es retorna `retryable: true`

Preguntes freqüents

Quant de temps és vàlida la URL signada?

Vida curta: minuts, no hores. La URL està signada per a una descàrrega d’un sol ús i rota a cada crida. Crida sempre get_audit_pdf de nou enlloc de cachejar la URL en si mateixa; la resposta és econòmica quan el render ja està complet.

Puc personalitzar la marca del PDF?

La marca (logo, nom d’empresa, color d’accent, peu) es configura al dashboard a Settings → Branding i s’aplica automàticament als PDFs renderitzats per a aquest compte. L’eina MCP no accepta overrides per crida a la v1.

Què hi ha al PDF que no és a `get_audit`?

El PDF és el lliurable de cara a persones: portada, resum executiu, seccions per mòdul amb captures de pantalla, i la mateixa llista de findings amb text de recomanació més llarg. get_audit és el JSON estructurat per a agents; el PDF és la versió que donaries a un client.