Installazione

Docker

L’immagine pubblicata è la strada più corta per entrare, ed è quella che il resto della documentazione dà per scontata.

Il volume conta. mcpd scrive un database SQLite nel percorso che MCPD_DATA indica, e un container senza volume si porta via le tue tracce quando si ferma. Indicare il percorso in modo esplicito costa un’opzione e toglie di mezzo la domanda su dove sia finito il file.

Ogni opzione ha una variabile d’ambiente, quindi tutto quello che puoi passare da riga di comando lo puoi anche impostare con -e. Fissa un tag invece di seguire latest in qualunque cosa a cui tieni. L’immagine è costruita per linux/amd64 e linux/arm64, e Docker scarica quella adatta alla tua macchina.

Docker Compose

Lo stesso container, messo per iscritto. È la forma da usare quando mcpd sta accanto alla tua applicazione su un solo host.

services:
  mcpd:
    image: ghcr.io/mcpd/mcpd:latest
    restart: unless-stopped
    ports:
      - "4317:4317"
    volumes:
      - mcpd-data:/data
    environment:
      MCPD_DATA: /data/mcpd.db
      MCPD_PROJECT: default
      # Impostale prima che questa porta sia raggiungibile da altri.
      # MCPD_INGEST_KEYS: key-for-your-agents
      # MCPD_READ_KEYS: key-for-your-team
      # MCPD_RETENTION_DAYS: 30

volumes:
  mcpd-data:

Le tre chiavi commentate sono quelle da riempire prima che tutto questo arrivi su una rete dove c’è anche qualcun altro. Senza nessuna chiave impostata, l’ingest e le letture sono entrambi aperti: giusto sul tuo portatile e sbagliato in ogni altro posto. Deploy spiega che cosa impostare e perché.

Kubernetes

Ogni release carica il chart nello stesso registry dell’immagine, come artefatto OCI, quindi non c’è nessun repository da aggiungere prima. Il chart rifiuta l’installazione senza una chiave di ingest e una chiave di lettura, quindi genera prima tutte e due.

mcpd gestisce SIGTERM e si spegne in modo ordinato, ed è quello che manda Kubernetes. Espone /healthz per la liveness e /readyz per la readiness, e i due sono diversi apposta: la liveness non tocca mai lo storage, così un database lento non può far ripartire il pod dentro un ciclo. I values, le sonde e la forma del Deployment stanno su Docker e Kubernetes.

Un binario di release

Ogni release allega un archivio per Linux su x86_64 e arm64, statico e compilato con musl, così non c’è nessuna libc da far combaciare, e uno per macOS su Apple silicon e su Intel. Insieme arrivano un file SHA256SUMS e un’attestazione di provenienza della build. Estrai l’archivio della tua macchina e lancia ./mcpd: senza argomenti avvia il daemon.

Non esiste cargo install mcpd. Su crates.io non è pubblicato niente, e un crate compilato dal registry non potrebbe portarsi dietro l’interfaccia, che si costruisce con npm e viene compilata dentro il binario. Se hai una toolchain Rust, compila dai sorgenti.

Dai sorgenti

Clona il repository e lancia la build di distribuzione. Quella build usa l’ottimizzazione link-time completa e una sola unità di codegen: è più lenta da compilare e produce il binario più piccolo e più veloce. Passa da make invece che direttamente da cargo: l’interfaccia è compilata dentro il binario, e make dist la costruisce prima, che è il passaggio che un semplice cargo build su un clone appena fatto non ha modo di fare. Quel passaggio richiede Node e npm sulla macchina, oltre alla toolchain Rust.

Il binario viene scritto in target/dist/mcpd, oppure in target/release/mcpd se hai preso la strada più veloce. Usa make build mentre lavori su mcpd stesso e make dist per qualsiasi cosa che intendi mandare in esecuzione.

Dove finiscono i dati

--data è il percorso del file SQLite, e per impostazione predefinita vale ./mcpd.db nella directory di lavoro. Le directory padre vengono create per te.

Passare :memory: tiene tutto in memoria e non scrive niente su disco. È la scelta giusta per una suite di test, per una demo sulla macchina di qualcun altro e per qualsiasi esecuzione i cui prompt preferiresti non lasciare in giro. Lo storage sparisce insieme al processo, ed è proprio questo il punto.

mcpd demo riempie lo storage con un’esecuzione fallita realistica e poi si mette a servire, così l’interfaccia ha già qualcosa dentro la prima volta che la apri.

Controlla che cosa farà prima di avviarlo

mcpd config stampa la configurazione a cui si risolve questa invocazione, poi esce. Opzioni, variabili d’ambiente e valori predefiniti finiscono tutti in un solo elenco, così vedi quale ha vinto senza avviare niente.

$ mcpd configlisten          0.0.0.0:4317storage         sqlite at ./mcpd.dbconfig file     nonelog format      textproject         defaultprojects        noneretention       foreveringest auth     openread auth       openwrite auth      openadmin auth      openexecute auth    openworker auth     opensignup          offruns            sqlite at ./mcpd.runs.dbrun settings    lease_ttl_ms 30000, reclaim_window_ms 30000, stall_window_ms 300000, idempotency_window_ms 86400000, park_ttl_ms 86400000, max_depth 8, max_step_repeats 16identity        offclient ip       peer addresssampling        keep everythingquota           unlimitedredaction       onredact key      built in, which is public; set --redact-keycors            same-origin onlytimeout         30s per requestlimits          32 MiB per request, 10000 signals per batchderived         duration and token metricsaspects         offmonitors        noneobjectives      nonejudge           offforwarding      off

Verifica l’installazione

/healthz è la risposta a «sta davvero girando?». Non legge mai dallo storage, quindi resta veloce e resta onesto sul processo invece che sul disco.

$ curl -s localhost:4317/healthz{"status":"ok","version":"0.1.0","spec_version":"1.0.0","uptime_seconds":8,"storage":"sqlite"}$ curl -s -o /dev/null -w "%{http_code}\n" localhost:4317/readyz200

spec_version è la versione del modello dei dati che questa build implementa. Un client può leggerla e rifiutarsi di parlare con un server che non capisce, il che è meglio che spedire un batch che verrà rifiutato campo per campo.

/readyz è l’altra metà. Interroga lo storage e risponde 503 quando non lo raggiunge, così un load balancer smette di mandare letture a un’istanza che non può servirle. Usa /healthz per la liveness e /readyz per la readiness, mai lo stesso per tutte e due.

Poi apri localhost:4317 e hai davanti l’interfaccia.

Da leggere dopo

• Mandagli una traccia dal tuo agente: Avvio rapido.
• Impara le parole che usa il resto della documentazione: Concetti.
• Ogni opzione e ogni variabile d’ambiente in una sola tabella: Configurazione.
• Prima che qualcun altro possa raggiungere la porta: Docker e Kubernetes.