get_audit_pdf - Docs do MetricSpot

O que esta ferramenta faz

get_audit_pdf devolve um URL assinado para descarregar o relatório PDF com marca de uma dada auditoria. Se ainda não foi renderizado nenhum PDF, põe um render em fila e devolve o estado queued.

Recebe um audit_id (o mesmo valor que run_audit devolveu).
Devolve audit_id, pdf_url, e status (ready ou queued).
O URL assinado é de curta duração; trata-o como descartável e vai buscá-lo imediatamente.
Se status: queued, chama a ferramenta de novo passados alguns segundos, ou acede ao URL quando o render terminar.
A marca white-label (logótipo, nome da empresa, tema) segue o plano do utilizador e as definições do dashboard.

Por que importa

O PDF é o entregável que a maior parte dos consultores e agências entrega aos clientes. Permitir que um agente apanhe um URL assinado significa que uma única chamada MCP pode terminar um fluxo ponta-a-ponta de “auditar e reportar” que antes exigia uma aba do dashboard.

Fluxos concretos:

Um agente “relatório de cliente” corre run_audit, faz polling a get_audit, depois chama get_audit_pdf e anexa o URL assinado a um rascunho de email.
Um agente “arquivar último trimestre” percorre list_audits, vai buscar cada PDF, e guarda-os no Drive ou S3 com o URL e created_at como nome de ficheiro.

Como usá-la

get_audit_pdf é um POST por baixo, a primeira chamada dispara um render se a cache estiver fria. Se o PDF foi renderizado recentemente, o URL volta imediatamente. Caso contrário espera 5-15 s de tempo de render; faz polling à ferramenta de poucos em poucos segundos.

Schema de entrada

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

Amostra do schema de resposta

{
  "audit_id": "aud_01HZ8X9YP7K3T2N6Q5",
  "pdf_url": "https://cdn.metricspot.com/reports/aud_01HZ8X9YP7K3T2N6Q5.pdf?signature=...",
  "status": "ready"
}

Quando o render ainda está em curso:

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

Pede:

Vai buscar o PDF da auditoria aud_01HZ8X9YP7K3T2N6Q5 ao MetricSpot e dá-me o link de descarga.

Cursor

.cursor/mcp.json:

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

Pede:

Vai buscar a última auditoria de example.com, espera pelo PDF, e descarrega-o para ./reports.

Python (polling até estar pronto, depois 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 direto)

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

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)	A exportação PDF exige um plano pago em algumas contas	Faz upgrade em `https://app.metricspot.com/billing`
`UPSTREAM_FAILED` (5xx)	Falha pontual no serviço de render	Tenta uma vez; `retryable: true` está definido

Perguntas frequentes

Durante quanto tempo é válido o URL assinado?

Curta duração: minutos, não horas. O URL é assinado para descarga única e roda a cada chamada. Volta sempre a chamar get_audit_pdf em vez de cachear o URL em si; a resposta é barata quando o render já está completo.

Posso personalizar a marca do PDF?

A marca (logótipo, nome da empresa, cor de destaque, rodapé) é definida no dashboard em Settings → Branding e aplicada automaticamente aos PDFs renderizados para essa conta. A ferramenta MCP não aceita overrides por chamada na v1.

O que está no PDF que não está em `get_audit`?

O PDF é o entregável voltado para humanos: capa, sumário executivo, secções por módulo com capturas de ecrã, e a mesma lista de descobertas com texto de recomendação mais longo. get_audit é o JSON estruturado para agentes; o PDF é a versão que entregarias a um cliente.