Instalação

Docker

A imagem publicada é o caminho de entrada mais curto, e é o que o resto da documentação pressupõe.

O volume importa. O mcpd escreve um banco de dados SQLite no caminho que MCPD_DATA nomeia, e um contêiner sem volume leva os seus traces junto quando para. Nomear o caminho de forma explícita custa uma opção e tira a dúvida de para onde foi o arquivo.

Toda opção tem uma variável de ambiente, então tudo que você pode passar na linha de comando também dá para definir com -e. Fixe uma tag em vez de acompanhar latest em qualquer coisa com que você se importe. A imagem é construída para linux/amd64 e linux/arm64, e o Docker baixa a que corresponde à sua máquina.

Docker Compose

O mesmo contêiner, por escrito. Esta é a forma a usar quando o mcpd fica ao lado da sua aplicação em um único 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
      # Set these before this port is reachable by anything but you.
      # MCPD_INGEST_KEYS: key-for-your-agents
      # MCPD_READ_KEYS: key-for-your-team
      # MCPD_RETENTION_DAYS: 30

volumes:
  mcpd-data:

As três chaves comentadas são as que você preenche antes que isto chegue a uma rede em que haja mais alguém. Sem nenhuma chave definida, a ingestão e as leituras ficam as duas abertas, o que está certo no seu notebook e errado em todo o resto. Implantação cobre o que definir e por quê.

Kubernetes

Cada release publica o chart no mesmo registro da imagem, como um artefato OCI, então não há repositório para adicionar antes. O chart se recusa a instalar sem uma chave de ingestão e uma chave de leitura, então gere as duas antes.

O mcpd trata SIGTERM e desliga de forma limpa, que é o que o Kubernetes envia. Ele expõe /healthz para liveness e /readyz para readiness, e os dois são diferentes de propósito: o liveness nunca toca no armazenamento, então um banco de dados lento não consegue reiniciar o pod em laço. Os values, as probes e o formato do Deployment estão em Docker e Kubernetes.

Um binário de release

Cada release anexa um arquivo para Linux em x86_64 e arm64, estático e compilado com musl para não haver libc a combinar, e para macOS em Apple silicon e Intel. Um arquivo SHA256SUMS e uma atestação de proveniência do build vêm junto. Descompacte o arquivo da sua máquina e rode ./mcpd; sem argumentos ele inicia o daemon.

Não existe cargo install mcpd. Nada é publicado no crates.io, e um crate compilado a partir do registro não conseguiria levar a interface, que é construída com npm e compilada dentro do binário. Com uma toolchain Rust, compile a partir do código.

A partir do código

Clone o repositório e rode o build de distribuição. Ele usa otimização de link completa e uma única unidade de codegen, o que compila mais devagar e produz o binário menor e mais rápido. Vá por make em vez de cargo direto: a interface é compilada dentro do binário, e make dist a constrói antes, que é a etapa que um cargo build puro em um clone novo não tem como fazer. Essa etapa precisa de Node e npm na máquina, além da toolchain Rust.

O binário é escrito em target/dist/mcpd, ou em target/release/mcpd se você pegou o caminho mais rápido. Use make build enquanto trabalha no próprio mcpd e make dist para qualquer coisa que você pretenda executar.

Para onde vão os dados

--data é o caminho do arquivo SQLite, e o padrão é ./mcpd.db no diretório de trabalho. Os diretórios acima são criados para você.

Passar :memory: mantém tudo em memória e não escreve nada em disco. Essa é a escolha certa para uma suíte de testes, para uma demonstração na máquina de outra pessoa e para qualquer execução cujos prompts você prefere não deixar para trás. O armazenamento desaparece junto com o processo, e é esse o objetivo.

mcpd demo preenche o armazenamento com uma execução que falha de um jeito realista e depois serve, para que a interface tenha alguma coisa dentro na primeira vez que você a abre.

Veja o que ele vai fazer antes de iniciar

mcpd config imprime a configuração para a qual esta invocação se resolve, e então sai. Flags, variáveis de ambiente e padrões terminam todos em uma única listagem, então dá para ver qual deles venceu sem iniciar nada.

$ 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

Verifique a instalação

/healthz é a resposta para “isto está mesmo rodando”. Ele nunca lê do armazenamento, então continua rápido e continua honesto sobre o processo, e não sobre o 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 é a versão do modelo de dados que este build implementa. Um cliente pode ler esse valor e se recusar a falar com um servidor que não entende, o que é melhor do que enviar um lote que vai ser rejeitado campo a campo.

/readyz é a outra metade. Ele consulta o armazenamento e responde 503 quando o armazenamento não está acessível, para que um balanceador de carga pare de mandar leituras para uma instância que não consegue atendê-las. Use /healthz para liveness e /readyz para readiness, nunca o mesmo para os dois.

Depois abra localhost:4317 e você está diante da interface.

Em seguida

• Mande um trace do seu próprio agente: Início rápido.
• Aprenda as palavras que o resto da documentação usa: Conceitos.
• Toda opção e variável de ambiente em uma única tabela: Configuração.
• Antes que mais alguém alcance a porta: Docker e Kubernetes.