attest-mcp

https://github.com/SPAZIO-GENESI/attest-mcp

Documentação

attest-mcp

Listado no registro oficial de MCP como io.github.SPAZIO-GENESI/attest-mcp.

Servidor MCP e CLI para o serviço de atestação da Spazio Genesi — ateste, verifique e confira a existência de obras digitais a partir de qualquer agente de IA compatível com MCP (Claude Code, Claude Desktop, etc.) ou diretamente de um terminal / pipeline de CI.

Privacidade total: os bytes do arquivo nunca saem do seu dispositivo. A impressão digital (SHA-256) é calculada localmente, transmitida em fluxo contínuo do disco — apenas o hash e metadados opcionais são enviados.

📖 Documentação em inglês: attestazione.spaziogenesi.org/en — site, documentação para desenvolvedores e níveis/termos estão todos disponíveis em inglês.

O que faz

O serviço de atestação registra a data e hora da impressão digital SHA-256 de um arquivo, assina (HMAC) e pode gerar um certificado PDF assinado além de uma prova OpenTimestamps ancorada no Bitcoin. Este servidor expõe esse serviço como ferramentas MCP, permitindo que um agente ateste e verifique obras em seu nome sem precisar de um navegador.

Por que isto, e não apenas um wrapper do OpenTimestamps

Vários servidores MCP podem enviar um hash para um calendário OpenTimestamps. Pelo que sabemos, este é o único que devolve uma prova completa de existência — um certificado PDF assinado, um timestamp reconhecido RFC 3161 e uma âncora Bitcoin — gratuitamente, sem que os bytes do arquivo saiam da máquina do chamador. Sem conta, sem upload, sem cadeia de notarização paga. Se você conhece outro servidor MCP com a mesma combinação (certificado completo + gratuito + hash local), gostaríamos muito de saber — abra uma issue.

Feito para o contexto jurídico e regulatório europeu

A Spazio Genesi é uma organização sem fins lucrativos italiana (ETS – Ente del Terzo Settore). O serviço de atestação por trás deste pacote foi projetado pensando no ambiente regulatório da UE, não adaptado a ele posteriormente:

Prioridade GDPR, privacidade por design: o arquivo em si nunca chega aos nossos servidores — apenas sua impressão digital SHA-256 (e quaisquer metadados que você optar por declarar) é enviada.
Residência de dados na UE: certificados e provas são arquivados no Cloudflare R2 sob jurisdição da UE.
Timestamp reconhecido, sem ponto único de confiança: cada certificado carrega um timestamp RFC 3161 de uma autoridade com raiz AATL (confiável pela Adobe e pela maioria dos leitores de PDF) e uma âncora Bitcoin independente via OpenTimestamps.
Transparência sobre eIDAS: este não é (ainda) um serviço de confiança qualificado eIDAS — a identidade do signatário é atualmente autoassinada, e um selo eletrônico qualificado é uma atualização planejada, mas não implementada. Consulte o whitepaper técnico para a análise completa e sem rodeios do que é e do que não é garantido.

Níveis e termos completos: attestazione.spaziogenesi.org/en/condizioni.

Instalação

Claude Desktop — um comando, sem edição manual de JSON:

npx -y @spazio-genesi/attest-mcp-setup

Isso encontra seu claude_desktop_config.json (Windows/macOS/Linux), adiciona a entrada attest-mcp e faz backup do arquivo original primeiro. Ele se recusa a tocar em qualquer coisa se o arquivo existente não for JSON válido — nunca adivinha. Reinicie o Claude Desktop depois. Para remover novamente: adicione --uninstall. Para visualizar sem gravar: adicione --dry-run.

Claude Code:

claude mcp add attest-mcp -- npx -y @spazio-genesi/attest-mcp

Manual / outros clientes — adicione isto à configuração do seu cliente MCP:

{
  "mcpServers": {
    "attest-mcp": {
      "command": "npx",
      "args": ["-y", "@spazio-genesi/attest-mcp"]
    }
  }
}

Autenticação

Duas formas de autenticar, correspondendo ao serviço subjacente:

Chave de API (para integrações de parceiros, emitida manualmente pela Spazio Genesi): defina a variável de ambiente IMGAUTH_API_KEY.
Fluxo de dispositivo (para uso pessoal/agente): chame a ferramenta authorize sem argumentos. Ela retorna uma URL — abra-a, aprove com o widget de verificação humana e chame authorize novamente com o código retornado. O token de sessão (24h, 20 atestações) é salvo em ~/.config/attest-mcp/credentials.json (permissões 600 onde suportado) e usado automaticamente depois disso.

De qualquer forma, a credencial apenas desbloqueia a verificação anti-bot na atestação — o timestamp do servidor, a assinatura criptográfica e os limites de taxa permanecem inalterados.

Ferramentas

Ferramenta	O que faz
`authorize`	Inicia ou continua a autorização do fluxo de dispositivo.
`attest_file`	Gera o hash de um arquivo local (em fluxo) e o atesta.
`get_certificate_pdf`	Emite um novo PDF assinado ou recupera um já arquivado, salvo em disco.
`verify_file`	Gera o hash de um arquivo local e o verifica contra um hash + assinatura declarados.
`verify_certificate`	Verifica a assinatura de um certificado sem arquivo local.
`check_anchor`	Verifica/baixa a prova OpenTimestamps (Bitcoin).
`service_status`	Status de semáforo do serviço de atestação.

CLI (`sg-attest`)

Mesmo pacote, sem instalação separada. A CLI é um bin junto com o servidor MCP, compartilhando o mesmo código de hash/API/config — mesma privacidade total (hash local em fluxo, bytes do arquivo nunca enviados), mesmas credenciais.

npx -y -p @spazio-genesi/attest-mcp sg-attest attest ./work.png
npx -y -p @spazio-genesi/attest-mcp sg-attest verify ./work.png --hash <sha256>

(-p é obrigatório: sg-attest é um bin secundário do pacote, e npx -y @spazio-genesi/attest-mcp simples executa o servidor MCP.)

Uma vantagem sobre o site: sem limite de 1 GB. O navegador é limitado pelo WebCrypto (que carrega o arquivo inteiro na memória); esta CLI transmite do disco no Node, então pode atestar arquivos de qualquer tamanho.

Comando	O que faz	Credencial
`attest <file> [--title --author --year --note] [--pdf <out>]`	Hash local (em fluxo) → atesta → imprime impressão digital, atestação, HMAC. Nada é arquivado e nenhuma página `/c/<hash>` existe sem `--pdf`; apenas `--pdf <out>` emite o certificado assinado e imprime o link de verificação	Sim
`verify <file> [--hash <sha256>]`	Hash local; com `--hash`, compara (saída 2 se diferente); também informa status de arquivamento/âncora	Não
`verify-cert --hash --attestazione --hmac [--titolo --autore --anno --note]`	Verifica a assinatura HMAC de um certificado, sem arquivo local envolvido	Não
`cert <hash> [-o <file.pdf>]`	Recupera um certificado já arquivado	Não
`anchor <hash> [-o <file.ots>]`	Verifica/baixa a prova OpenTimestamps (Bitcoin)	Não
`status`	Status de semáforo do serviço	Não
`authorize`	Fluxo de dispositivo: imprime uma URL para aprovar, verifica, salva o token	—
`--version` / `--help`	Versão (de `package.json`) e uso	—

Todo comando aceita --json (emite um objeto JSON no stdout, para scripts) e --quiet (reduz a saída legível não essencial). Erros vão para o stderr; a CLI nunca imprime uma credencial (chave de API ou token de sessão) no stdout, stderr ou saída --json — mesma disciplina do servidor MCP.

Códigos de saída (um contrato estável, para CI/scripts):

Código	Significado
`0`	Sucesso / resultado positivo
`1`	Erro operacional (rede, autenticação, entrada inválida)
`2`	Resultado de verificação negativo (hash incompatível, assinatura inválida)

A autenticação é a mesma do servidor MCP: variável de ambiente IMGAUTH_API_KEY ou um token de sessão salvo por sg-attest authorize (fluxo de dispositivo). Não há flag --key — uma credencial na linha de comando acaba no histórico do shell; use a variável de ambiente (ou um segredo de CI).

Uma GitHub Action que usa esta CLI para atestar artefatos de build em CI vive em um repositório complementar: attest-action.

Binários autônomos (sem necessidade de Node)

Para uma máquina ou runner de CI sem Node.js, baixe um executável sg-attest pré-compilado da página de Releases — mesmos comandos, mesmo comportamento, nada para instalar.

SO	Arquitetura	Arquivo
Linux	x64	`sg-attest-linux-x64`
Linux	arm64	`sg-attest-linux-arm64`
macOS	Intel	`sg-attest-macos-x64`
macOS	Apple Silicon	`sg-attest-macos-arm64`
Windows	x64	`sg-attest-windows-x64.exe`
Windows	ARM64	`sg-attest-windows-arm64.exe`

Cada versão também inclui SHA256SUMS.txt. Verifique o download antes de executá-lo:

sha256sum -c SHA256SUMS.txt --ignore-missing   # Linux/macOS

(Get-FileHash .\sg-attest-windows-x64.exe -Algorithm SHA256).Hash   # compare by eye to SHA256SUMS.txt

⚠️ Os binários não são assinados com código: espere um aviso de "editor desconhecido" do Windows SmartScreen ou do macOS Gatekeeper na primeira execução. O checksum acima é a garantia de integridade enquanto isso — o binário é construído e publicado pelo GitHub Actions diretamente do código-fonte deste repositório, nada enviado manualmente.

O uso é idêntico à CLI instalada via npm, basta chamar o arquivo diretamente:

chmod +x ./sg-attest-linux-x64          # Linux/macOS only
./sg-attest-linux-x64 attest ./work.png --pdf cert.pdf
./sg-attest-linux-x64 status

npx/npm continuam sendo o canal de distribuição principal (e o que attest-action usa em CI) — os binários são um canal adicional, não um substituto.

Proveniência do build (SLSA/in-toto)

O checksum acima responde "este arquivo está intacto?" — não diz nada sobre de onde os bytes vieram. Cada versão desde v0.4.2 também carrega uma atestação de proveniência de build assinada (actions/attest-build-provenance, job release em release-binaries.yml): prova criptográfica de que o arquivo foi construído pelo próprio workflow deste repositório, a partir de um commit e tag específicos, não enviado manualmente ou trocado depois.

A CLI do GitHub pode verificar, mas gh attestation verify exige uma sessão gh autenticada mesmo neste repositório público (confirmado: falha com "please run gh auth login" sem uma) — uma lacuna real se o objetivo é uma verificação que qualquer pessoa possa executar sem configuração:

gh attestation verify sg-attest-linux-x64 --repo SPAZIO-GENESI/attest-mcp

scripts/verify-provenance.mjs faz a mesma verificação sem nenhuma credencial do GitHub — apenas o endpoint REST público de atestações (confirmado acessível sem autenticação, mesmo neste repositório público) e a biblioteca sigstore, que verifica a assinatura contra a infraestrutura pública da própria Sigstore (Rekor, Fulcio, TUF — sem necessidade de conta lá também):

git clone https://github.com/SPAZIO-GENESI/attest-mcp
cd attest-mcp && npm install
node scripts/verify-provenance.mjs ./sg-attest-linux-x64 \
  --repo SPAZIO-GENESI/attest-mcp --tag v0.4.2

Sai com 0 em caso de sucesso, 1 se o arquivo não corresponder a nada que o workflow realmente construiu (por exemplo, um único byte alterado faz o digest — e portanto a própria chave de busca — não corresponder mais a nenhuma atestação).

Configuração

Variável de ambiente	Padrão	Finalidade
`IMGAUTH_API_KEY`	—	Credencial de chave de API, ignora o fluxo de dispositivo.
`IMGAUTH_BASE_URL`	`https://imgauth.spaziogenesi.org`	Substituição para desenvolvimento local (`http://localhost:8787`).
`IMGAUTH_CERT_PAGE_BASE`	`https://attestazione.spaziogenesi.org`	Substituição para a URL base da página de certificado permanente.

Solução de problemas

Se seu cliente relatar "Server disconnected", verifique o log primeiro: este servidor escreve diagnósticos no stderr, que os clientes MCP capturam. No Claude Desktop, o log fica em %APPDATA%\Claude\logs\mcp-server-attest-mcp.log (Windows) ou ~/Library/Logs/Claude/mcp-server-attest-mcp.log (macOS).

Você deve ver uma linha por evento de ciclo de vida:

[attest-mcp 2026-07-21T11:14:12.948Z] v0.2.2 ready on stdio (node v22.22.2, pid 32316)
[attest-mcp 2026-07-21T11:14:12.965Z] exiting (code 0)

exiting (code 0) — desligamento normal: o cliente fechou o stdin. Após suspensão do laptop ou reinício do cliente, isso é esperado; basta reiniciar o cliente para reconectar.
fatal: … seguido de exiting (code 1) — uma falha real, com o stack trace na linha anterior. Por favor, abra uma issue com ele.
Nenhuma linha ready — o processo nunca iniciou: verifique se node está no PATH e pelo menos na v18 (node --version).

O stdout carrega o protocolo JSON-RPC e nunca é usado para registro.

Limitação conhecida

O PDF do certificado e seu texto estão em italiano (a Spazio Genesi é uma organização sem fins lucrativos italiana e o certificado é um documento jurídico). As descrições das ferramentas MCP e este README estão em inglês para um público internacional.

Desenvolvimento

npm install
npm test          # unit tests (hash vectors, CLI argument parsing)
IMGAUTH_BASE_URL=http://localhost:8787 npm start   # MCP server against a local `wrangler dev`
IMGAUTH_BASE_URL=http://localhost:8787 node src/cli.js status   # CLI against the same

test/cli-smoke.local.mjs é um harness apenas local (não executado por npm test) que exercita cada comando sg-attest de ponta a ponta contra uma instância wrangler dev imgauth isolada — consulte o comentário de cabeçalho nesse arquivo para as variáveis de ambiente necessárias.

Segurança

Relate vulnerabilidades → /sicurezza/ (política de divulgação responsável, safe harbor para pesquisa de boa-fé) — este repositório não tem security.txt próprio (pacote npm, sem ativos estáticos), mas a política cobre todo o projeto.

Contribuindo

Relatórios de bugs e solicitações de recursos: abra uma issue. Pull requests são bem-vindos — mantenha-os focados (uma mudança por PR), garanta que npm test passe e explique o "porquê" na descrição, não apenas o "o quê". Política de testes: qualquer PR que adicione nova funcionalidade deve adicionar um teste para ela em test/; npm run lint e npm test ambos rodam no CI a cada push e pull request. Para qualquer coisa que toque o contrato de atestação em si (hashing, verificação HMAC, a superfície da API), abra uma issue primeiro: este cliente espelha um contrato de propriedade de imgauth, então as mudanças precisam permanecer compatíveis com ele.

Licença

MIT — veja LICENSE. Este é um cliente para o serviço de atestação; o próprio serviço (imgauth) é AGPL-3.0.

attest-mcp

Documentação

attest-mcp

O que faz

Por que isto, e não apenas um wrapper do OpenTimestamps

Feito para o contexto jurídico e regulatório europeu

Instalação

Autenticação

Ferramentas

CLI (sg-attest)

Binários autônomos (sem necessidade de Node)

Proveniência do build (SLSA/in-toto)

Configuração

Solução de problemas

Limitação conhecida

Desenvolvimento

Segurança

Contribuindo

Licença

CLI (`sg-attest`)