설치

Docker

배포된 이미지가 가장 짧은 길이고, 나머지 문서가 전제하는 길입니다.

볼륨은 중요합니다. mcpd는 MCPD_DATA가 가리키는 경로에 SQLite 데이터베이스를 씁니다. 볼륨 없는 컨테이너는 멈출 때 트레이스를 함께 가져갑니다. 경로를 분명히 적어 두는 데 드는 비용은 플래그 하나이고, 그 대신 파일이 어디로 갔는지 묻는 일이 없어집니다.

모든 플래그에는 대응하는 환경 변수가 있으므로, 명령줄로 넘길 수 있는 것은 -e로도 설정할 수 있습니다. 중요한 곳에서는 latest를 따라가지 말고 태그를 고정하십시오. 이미지는 linux/amd64와 linux/arm64용으로 빌드되며, Docker가 머신에 맞는 쪽을 받아 옵니다.

Docker Compose

같은 컨테이너를 파일로 적어 둔 것입니다. mcpd가 한 호스트에서 애플리케이션 옆에 놓일 때 쓰는 형태입니다.

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:

주석 처리된 키 세 개는 다른 사람이 있는 네트워크에 이것이 놓이기 전에 채워야 할 항목입니다. 키를 하나도 설정하지 않으면 수집과 읽기가 모두 열려 있습니다. 노트북에서는 맞는 상태이고, 그 밖의 모든 곳에서는 틀린 상태입니다. 무엇을 왜 설정해야 하는지는 배포 문서에서 다룹니다.

Kubernetes

릴리스마다 차트를 이미지와 같은 레지스트리에 OCI 아티팩트로 올리므로, 먼저 추가할 저장소가 없습니다. 차트는 수집 키와 읽기 키 없이는 설치를 거부하므로, 두 키를 먼저 만드십시오.

mcpd는 Kubernetes가 보내는 SIGTERM을 처리하고 정상적으로 종료합니다. 라이브니스용으로 /healthz를, 레디니스용으로 /readyz를 제공하며, 둘이 다른 것은 의도한 것입니다. 라이브니스는 스토리지를 건드리지 않으므로, 느린 데이터베이스 때문에 파드가 재시작 루프에 빠지는 일이 없습니다. values와 프로브와 Deployment 형태는 Docker와 Kubernetes에 있습니다.

릴리스 바이너리

릴리스마다 x86_64와 arm64 Linux용 아카이브와 Apple silicon과 Intel macOS용 아카이브가 붙습니다. Linux용은 musl로 빌드한 정적 바이너리라서 맞춰야 할 libc가 없습니다. SHA256SUMS 파일과 빌드 출처 증명(provenance attestation)이 함께 붙습니다. 머신에 맞는 아카이브를 풀고 ./mcpd를 실행하십시오. 인자 없이 실행하면 데몬이 시작됩니다.

cargo install mcpd는 없습니다. crates.io에는 아무것도 배포되지 않았고, 레지스트리에서 빌드한 크레이트는 인터페이스를 담을 수 없습니다. 인터페이스는 npm으로 빌드해 바이너리 안에 컴파일해 넣기 때문입니다. Rust 툴체인이 있다면 대신 소스에서 빌드하십시오.

소스에서 빌드

저장소를 클론하고 배포 빌드를 실행합니다. 이 빌드는 링크 타임 최적화를 전부 켜고 코드젠 유닛을 하나만 쓰므로, 컴파일은 더 오래 걸리고 결과 바이너리는 더 작고 더 빠릅니다. cargo를 직접 부르지 말고 make를 거치십시오. 인터페이스가 바이너리 안에 컴파일되어 들어가는데, make dist가 그것을 먼저 빌드합니다. 갓 클론한 저장소에서 cargo build만으로는 할 수 없는 단계입니다. 그 단계에는 Rust 툴체인 외에 머신의 Node와 npm도 필요합니다.

바이너리는 target/dist/mcpd에 쓰이고, 더 빠른 길을 골랐다면 target/release/mcpd에 쓰입니다. mcpd 자체를 고치는 동안에는 make build를, 실제로 돌릴 것에는 make dist를 쓰십시오.

데이터가 놓이는 곳

--data는 SQLite 파일의 경로이고, 기본값은 작업 디렉터리의 ./mcpd.db입니다. 상위 디렉터리는 알아서 만들어 줍니다.

:memory:를 넘기면 모든 것을 메모리에 두고 디스크에는 아무것도 쓰지 않습니다. 테스트 스위트, 남의 머신에서 하는 시연, 그리고 프롬프트를 남기고 싶지 않은 실행에는 이쪽이 맞습니다. 저장소는 프로세스와 함께 사라지고, 그것이 이 설정의 목적입니다.

mcpd demo는 실제로 있을 법한 실패한 실행을 저장소에 채운 다음 서비스를 시작합니다. 그래서 인터페이스를 처음 열었을 때 볼 것이 들어 있습니다.

시작하기 전에 무엇을 할지 확인

mcpd config는 이번 호출이 확정한 설정을 출력하고 종료합니다. 플래그와 환경 변수와 기본값이 한 목록에 모이므로, 아무것도 시작하지 않고 어느 쪽이 이겼는지 볼 수 있습니다.

$ 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

설치 확인

/healthz는 "정말 돌고 있는가"에 대한 답입니다. 스토리지를 읽는 일이 없으므로 빠르고, 디스크가 아니라 프로세스에 대해 정직합니다.

$ 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은 이 빌드가 구현한 데이터 모델의 버전입니다. 클라이언트는 그것을 읽고, 이해하지 못하는 서버와는 통신을 거부할 수 있습니다. 필드마다 거절당할 배치를 보내는 것보다 낫습니다.

/readyz는 나머지 절반입니다. 스토리지를 한 번 두드려 보고, 저장소에 닿지 않으면 503으로 답합니다. 그래서 로드 밸런서가 읽기를 처리하지 못하는 인스턴스로 읽기를 더 보내지 않습니다. 라이브니스에는 /healthz를, 레디니스에는 /readyz를 쓰고, 둘 다에 같은 것을 쓰지는 마십시오.

그다음 localhost:4317을 열면 인터페이스가 보입니다.

다음

• 직접 만든 에이전트에서 트레이스를 보내려면: 빠른 시작.
• 나머지 문서가 쓰는 용어를 익히려면: 개념.
• 모든 플래그와 환경 변수를 표 하나로 보려면: 설정.
• 다른 사람이 이 포트에 닿을 수 있게 되기 전에: Docker와 Kubernetes.