mcpg plugin (plugin artifacts)
Package, sign, push, pull, and test MCPG plugin artifacts — invoked directly (mcpg-plugin) or via mcpg plugin <cmd>.
mcpg plugin — plugin artifacts
mcpg plugin <cmd> transparently execs the mcpg-plugin binary on $PATH.
The crate (mcpg-plugin) is publish = false (not on crates.io), so install
it from the workspace source: cargo install --path apps/plugin (or build
without installing: cargo build -p mcpg-plugin). You can run either form —
they're identical: mcpg plugin push … ≡ mcpg-plugin push ….
mcpg-plugin manages plugin artifact files: it packages a built .so /
.wasm + its plugin.yaml descriptor (+ optional signature) into a ZIP, signs
and hashes it, and pushes/pulls it as an OCI 1.1 artifact. It does not
compile plugins or generate keys (use cargo build and ssh-keygen).
| Command | Purpose |
|---|---|
new --kind <K> --name <N> [--id …] [--out …] | Scaffold a new plugin crate (one of 21 kinds, e.g. tool_gate, transform, backend). |
hash <artifact> | Print the SHA-256 (sha256:…) for use in config integrity.sha256. |
sign (--key <seed> | --subprocess <cmd> --public-key <hex|file:…>) <artifact> | Create an Ed25519 detached .sig (local seed file or KMS/HSM subprocess). |
verify [--key <pub>] [--hash <hex>] <artifact> | Verify hash and/or signature; non-zero exit on mismatch. |
list [<dir>] | List .so/.dylib/.wasm in a dir (truncated hash, kind, [signed]). Defaults to $MCPG_PLUGIN_DIR or .. |
pack -d <plugin.yaml> -a <artifact> -v <ver> [-s <sig>] [--os …] [--arch …] [-o <out.zip>] | Bundle descriptor + artifact (+ sig) into a distributable ZIP. |
unpack <archive.zip> <target-dir> | Extract a packaged plugin and print its descriptor fields. |
push <archive.zip> <registry/repo:tag> [-u <user> -p <pw|env:VAR>] [--docker-config …] [--insecure-registry …] | Publish the package to an OCI registry as an MCPG artifact. |
pull <registry/repo:tag> [-o <out.zip>] [auth flags] | Fetch a packaged plugin to disk. |
cache gc [--keep-latest N] [--older-than 7d] [--dry-run] [--cache-dir …] | GC the local OCI unpack cache (conservative: removes nothing without --older-than). |
test <archive.zip> [--descriptor …] [--context …] [--arguments …] [--config …] [--key <pub>] | Load a package into an in-process mock gateway and exercise its FFI vtable. |
Examples
# Build → hash → sign → pack → push
cargo build --release
mcpg plugin hash target/release/libmcpg_plugin_audit.so
mcpg plugin sign --key ./signing.seed target/release/libmcpg_plugin_audit.so
mcpg plugin pack -d plugin.yaml -a target/release/libmcpg_plugin_audit.so \
-v 1.0.0 -s target/release/libmcpg_plugin_audit.so.sig -o audit_1.0.0.zip
mcpg plugin push audit_1.0.0.zip ghcr.io/mcpg-dev/plugins/audit:1.0.0 -u andrii -p env:GHCR_TOKEN
# Consume + verify + smoke-test
mcpg plugin pull ghcr.io/mcpg-dev/plugins/audit:1.0.0 -o ./audit.zip
mcpg plugin test ./audit.zip --arguments args.json --config cfg.json --key audit.pub
# KMS signer, cross-checked against a known public key
mcpg plugin sign --subprocess 'gcloud kms asymmetric-sign … | tail -c 64' \
--public-key file:audit.pub target/release/libmcpg_plugin_audit.so
Authentication for push/pull
Priority: -u/-p flags (use -p env:VAR to read a secret from the
environment) → --docker-config <path> → ~/.docker/config.json (unless
--no-docker-config) → anonymous. --insecure-registry <host> allows plain
HTTP for that host (localhost is always plain HTTP).
Artifact format
A package is a ZIP containing plugin.yaml (descriptor) + exactly one of
plugin.so/plugin.wasm + an optional plugin.sig. On a registry it's an OCI
1.1 artifact (artifactType: application/vnd.mcpg.plugin.v1) — docker pull
deliberately rejects it; the gateway and mcpg-plugin pull understand it.