attest-mcp

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

Documentación

attest-mcp

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

Servidor MCP y CLI para el servicio de certificación de Spazio Genesi — certifica, verifica y comprueba la existencia de obras digitales desde cualquier agente de IA compatible con MCP (Claude Code, Claude Desktop, etc.) o directamente desde una terminal / pipeline de CI.

Privacidad total: los bytes del archivo nunca salen de tu dispositivo. La huella digital (SHA-256) se calcula localmente, transmitida desde el disco — solo se envían el hash y los metadatos opcionales.

📖 Documentación en inglés: attestazione.spaziogenesi.org/en — sitio, documentación para desarrolladores y niveles/términos están disponibles en inglés.

Qué hace

El servicio de certificación añade una marca de tiempo a la huella digital SHA-256 de un archivo, la firma (HMAC) y puede generar un certificado PDF firmado además de una prueba OpenTimestamps anclada en Bitcoin. Este servidor expone ese servicio como herramientas MCP, para que un agente pueda certificar y verificar obras en tu nombre sin necesidad de un navegador.

Por qué esto, y no solo un envoltorio de OpenTimestamps

Varios servidores MCP pueden enviar un hash a un calendario de OpenTimestamps. Hasta donde sabemos, este es el único que devuelve una prueba completa de existencia — un certificado PDF firmado, una marca de tiempo RFC 3161 reconocida y un ancla de Bitcoin — de forma gratuita, sin que los bytes del archivo salgan de la máquina del solicitante. Sin cuenta, sin carga, sin cadena de notarización de pago. Si conoces otro servidor MCP con la misma combinación (certificado completo + gratuito + hash local), nos gustaría saberlo de verdad — abre un issue.

Diseñado para el contexto legal y regulatorio europeo

Spazio Genesi es una organización sin fines de lucro italiana (ETS – Ente del Terzo Settore). El servicio de certificación detrás de este paquete fue diseñado teniendo en cuenta el entorno regulatorio de la UE, no adaptado a él después:

Prioridad GDPR, privacidad por diseño: el archivo en sí nunca llega a nuestros servidores — solo se envía su huella digital SHA-256 (y cualquier metadato que decidas declarar).
Residencia de datos en la UE: los certificados y las pruebas se archivan en Cloudflare R2 bajo jurisdicción de la UE.
Marca de tiempo reconocida, sin un único punto de confianza: cada certificado lleva una marca de tiempo RFC 3161 de una autoridad con raíz AATL (confiable para Adobe y la mayoría de los lectores de PDF) y un ancla de Bitcoin independiente mediante OpenTimestamps.
Transparencia sobre eIDAS: esto no es (aún) un servicio de confianza cualificado eIDAS — la identidad del firmante actualmente es autofirmada, y un sello electrónico cualificado es una mejora planificada pero no implementada. Consulta el documento técnico para el desglose completo y sin adornos de lo que está y no está garantizado.

Niveles y términos completos: attestazione.spaziogenesi.org/en/condizioni.

Instalación

Claude Desktop — un comando, sin edición manual de JSON:

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

Esto encuentra tu claude_desktop_config.json (Windows/macOS/Linux), añade la entrada attest-mcp y hace una copia de seguridad del archivo original primero. Se niega a tocar nada si el archivo existente no es JSON válido — nunca adivina. Reinicia Claude Desktop después. Para eliminarlo de nuevo: añade --uninstall. Para previsualizar sin escribir: añade --dry-run.

Claude Code:

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

Manual / otros clientes — añade esto a la configuración de tu cliente MCP:

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

Autenticación

Dos formas de autenticarse, que coinciden con el servicio subyacente:

Clave API (para integraciones de socios, emitida manualmente por Spazio Genesi): establece la variable de entorno IMGAUTH_API_KEY.
Flujo de dispositivo (para uso personal/agente): llama a la herramienta authorize sin argumentos. Devuelve una URL — ábrela, aprueba con el widget de verificación humana, luego llama a authorize de nuevo con el código devuelto. El token de sesión (24h, 20 certificaciones) se guarda en ~/.config/attest-mcp/credentials.json (permisos 600 donde se admita) y se usa automáticamente después.

De cualquier manera, la credencial solo desbloquea la verificación anti-bot en la certificación — la marca de tiempo del lado del servidor, la firma criptográfica y los límites de velocidad no cambian.

Herramientas

Herramienta	Qué hace
`authorize`	Inicia o continúa la autorización del flujo de dispositivo.
`attest_file`	Calcula el hash de un archivo local (transmitido) y lo certifica.
`get_certificate_pdf`	Genera un PDF firmado nuevo, o recupera uno ya archivado, guardado en disco.
`verify_file`	Calcula el hash de un archivo local y lo compara con un hash + firma declarados.
`verify_certificate`	Verifica la firma de un certificado sin un archivo local.
`check_anchor`	Comprueba/descarga la prueba OpenTimestamps (Bitcoin).
`service_status`	Estado tipo semáforo del servicio de certificación.

CLI (`sg-attest`)

Mismo paquete, sin instalación separada. La CLI es un bin junto al servidor MCP, compartiendo el mismo código de hash/API/configuración — misma privacidad total (hash local transmitido, los bytes del archivo nunca se envían), mismas credenciales.

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 es obligatorio: sg-attest es un bin secundario del paquete, y el simple npx -y @spazio-genesi/attest-mcp ejecuta el servidor MCP en su lugar.)

Una ventaja sobre el sitio: sin límite de 1 GB. El navegador está limitado por WebCrypto (que carga todo el archivo en memoria); esta CLI transmite desde disco en Node, por lo que puede certificar archivos de cualquier tamaño.

Comando	Qué hace	Credencial
`attest <file> [--title --author --year --note] [--pdf <out>]`	Hash local (transmitido) → certifica → imprime huella, certificación, HMAC. Nada se archiva y no existe ninguna página `/c/<hash>` sin `--pdf`; solo `--pdf <out>` genera el certificado firmado y imprime el enlace de verificación	Sí
`verify <file> [--hash <sha256>]`	Hash local; con `--hash`, compara (salida 2 si son diferentes); también informa del estado de archivo/ancla	No
`verify-cert --hash --attestazione --hmac [--titolo --autore --anno --note]`	Verifica la firma HMAC de un certificado, sin archivo local involucrado	No
`cert <hash> [-o <file.pdf>]`	Recupera un certificado ya archivado	No
`anchor <hash> [-o <file.ots>]`	Comprueba/descarga la prueba OpenTimestamps (Bitcoin)	No
`status`	Estado tipo semáforo del servicio	No
`authorize`	Flujo de dispositivo: imprime una URL para aprobar, sondea, guarda el token	—
`--version` / `--help`	Versión (de `package.json`) y uso	—

Cada comando acepta --json (emite un objeto JSON en stdout, para scripting) y --quiet (reduce la salida legible no esencial). Los errores van a stderr; la CLI nunca imprime una credencial (clave API o token de sesión) en stdout, stderr o la salida --json — misma disciplina que el servidor MCP.

Códigos de salida (un contrato estable, para CI/scripting):

Código	Significado
`0`	Éxito / resultado positivo
`1`	Error operativo (red, autenticación, entrada incorrecta)
`2`	Resultado de verificación negativo (discrepancia de hash, firma no válida)

La autenticación es la misma que la del servidor MCP: variable de entorno IMGAUTH_API_KEY, o un token de sesión guardado por sg-attest authorize (flujo de dispositivo). No hay bandera --key — una credencial en la línea de comandos termina en el historial del shell; usa la variable de entorno (o un secreto de CI) en su lugar.

Una GitHub Action que usa esta CLI para certificar artefactos de compilación en CI vive en un repositorio complementario: attest-action.

Binarios independientes (sin necesidad de Node)

Para una máquina o runner de CI sin Node.js, descarga un ejecutable sg-attest precompilado desde la página de Releases — mismos comandos, mismo comportamiento, nada que instalar.

SO	Arquitectura	Archivo
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 versión también incluye SHA256SUMS.txt. Verifica la descarga antes de ejecutarlo:

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

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

⚠️ Los binarios no están firmados con código: espera una advertencia de "editor desconocido" de Windows SmartScreen o macOS Gatekeeper la primera vez que ejecutes uno. El checksum anterior es la garantía de integridad mientras tanto — el binario se compila y publica mediante GitHub Actions directamente desde el código fuente de este repositorio, nada cargado manualmente.

El uso es idéntico a la CLI instalada con npm, solo llama al archivo directamente:

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 siguen siendo el canal de distribución principal (y lo que attest-action usa en CI) — los binarios son un canal adicional, no un reemplazo.

Procedencia de compilación (SLSA/in-toto)

El checksum anterior responde "¿está intacto este archivo?" — no dice nada sobre de dónde vinieron los bytes. Cada versión desde v0.4.2 también lleva una atestación de procedencia de compilación firmada (actions/attest-build-provenance, trabajo release en release-binaries.yml): prueba criptográfica de que el archivo fue compilado por el propio flujo de trabajo de este repositorio, desde un commit y una etiqueta específicos, no cargado manualmente ni intercambiado después.

La CLI de GitHub puede verificarlo, pero gh attestation verify requiere una sesión de gh autenticada incluso en este repositorio público (confirmado: falla con "please run gh auth login" sin una) — una brecha real si el punto es una verificación que cualquiera pueda ejecutar sin configuración:

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

scripts/verify-provenance.mjs hace la misma verificación sin credenciales de GitHub en absoluto — solo el endpoint REST público de atestaciones (confirmado accesible sin autenticación, incluso en este repositorio público) y la biblioteca sigstore, que verifica la firma contra la propia infraestructura pública de Sigstore (Rekor, Fulcio, TUF — tampoco se necesita cuenta allí):

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

Sale con 0 en caso de éxito, 1 si el archivo no coincide con nada que el flujo de trabajo realmente compiló (por ejemplo, un solo byte alterado hace que el digest — y por lo tanto la propia clave de búsqueda — ya no coincida con ninguna atestación).

Configuración

Variable de entorno	Predeterminado	Propósito
`IMGAUTH_API_KEY`	—	Credencial de clave API, omite el flujo de dispositivo.
`IMGAUTH_BASE_URL`	`https://imgauth.spaziogenesi.org`	Anulación para desarrollo local (`http://localhost:8787`).
`IMGAUTH_CERT_PAGE_BASE`	`https://attestazione.spaziogenesi.org`	Anulación para la URL base de la página de certificado permanente.

Solución de problemas

Si tu cliente informa "Server disconnected", revisa su registro primero: este servidor escribe diagnósticos en stderr, que los clientes MCP capturan. En Claude Desktop el registro se encuentra en %APPDATA%\Claude\logs\mcp-server-attest-mcp.log (Windows) o ~/Library/Logs/Claude/mcp-server-attest-mcp.log (macOS).

Deberías ver una línea por evento del 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) — apagado normal: el cliente cerró stdin. Después de una suspensión del portátil o un reinicio del cliente esto es esperado; solo reinicia el cliente para reconectar.
fatal: … seguido de exiting (code 1) — un fallo real, con el rastreo de pila en la línea anterior. Por favor abre un issue con él.
Sin línea ready en absoluto — el proceso nunca se inició: comprueba que node esté en PATH y al menos v18 (node --version).

stdout lleva el protocolo JSON-RPC y nunca se usa para registro.

Limitación conocida

El PDF del certificado y su texto están en italiano (Spazio Genesi es una organización sin fines de lucro italiana y el certificado es un documento orientado a lo legal). Las descripciones de las herramientas MCP y este README están en inglés para una audiencia internacional.

Desarrollo

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 es un arnés solo local (no ejecutado por npm test) que ejercita cada comando sg-attest de extremo a extremo contra una instancia aislada de wrangler dev imgauth — consulta el comentario de cabecera en ese archivo para las variables de entorno requeridas.

Seguridad

Reporta vulnerabilidades → /sicurezza/ (divulgación responsable, puerto seguro para investigación de buena fe) — este repositorio no tiene security.txt propio (paquete npm, sin activos estáticos), pero la política cubre todo el proyecto.

Contribuciones

Informes de errores y solicitudes de funciones: abre un issue. Las pull requests son bienvenidas — mantenlas enfocadas (un cambio por PR), asegúrate de que npm test pase, y explica el "por qué" en la descripción, no solo el "qué". Política de pruebas: cualquier PR que añada nueva funcionalidad debe añadir una prueba para ello en test/; npm run lint y npm test se ejecutan en CI en cada push y pull request. Para cualquier cosa que toque el contrato de atestación en sí (hashing, verificación HMAC, la superficie de la API), abre un issue primero: este cliente refleja un contrato propiedad de imgauth, por lo que los cambios deben mantenerse compatibles con él.

Licencia

MIT — consulta LICENSE. Este es un cliente para el servicio de atestación; el servicio en sí (imgauth) es AGPL-3.0.

attest-mcp

Documentación

attest-mcp

Qué hace

Por qué esto, y no solo un envoltorio de OpenTimestamps

Diseñado para el contexto legal y regulatorio europeo

Instalación

Autenticación

Herramientas

CLI (sg-attest)

Binarios independientes (sin necesidad de Node)

Procedencia de compilación (SLSA/in-toto)

Configuración

Solución de problemas

Limitación conocida

Desarrollo

Seguridad

Contribuciones

Licencia

CLI (`sg-attest`)