mcpg-plugins (plugin artifacts)

mcpg plugin <cmd> transparently execs the mcpg-plugins binary on $PATH, passing through MCPG_CONFIG and the rest of the environment. The two forms are identical: mcpg plugin push … is the same as mcpg-plugins push …. The crate is publish = false (not on crates.io), so build it from the workspace source (cargo build -p mcpg-plugins) or install it from the path.

mcpg-plugins manages plugin artifact files: it packages a built .so / .dylib / .wasm plus its plugin.yaml descriptor (and optional signature) into a ZIP, hashes and signs it, and pushes/pulls it as an OCI 1.1 artifact. It does not compile plugins (use cargo build) and does not generate signing keys (use ssh-keygen -t ed25519).

The argument parser is hand-rolled, not clap. The top-level mcpg-plugins help lists every command; mcpg-plugins version prints the version. Most subcommands take positional arguments and do not respond to --help (they treat it as a positional value) — new and test are the exceptions and print their own usage block.

Commands

new — the 21 plugin kinds

mcpg plugin new --kind <K> --name <N> scaffolds a crate under ./mcpg-plugin-<kind>-<name> (override with --out), with a plugin id of dev.example.<kind>.<name> unless --id is given. Every scaffold uses the unified declare_plugin! macro; tool_gate ships a fully-fleshed-out template, the others a stub pointing at the same entry point. The 21 kinds are:

tool_gate    transform        identity            backend
audit_sink   log_sink         metrics_sink        telemetry_sink
secret_provider  config_provider   store          cache
policy_engine    approval_notifier credential_issuer  catalog_provider
cluster      transport        http_route          watch_strategy
content_store

test — smoke-test against a mock gateway

mcpg plugin test <archive.zip> \
  [--descriptor <path>] [--context <json-file>] \
  [--arguments <json-file>] [--config <json-file>] \
  [--key <public-key>]

Loads the packaged plugin into an in-process mock gateway, exercises its vtable contract, and prints the decision as JSON (exit 0 if respected, 1 otherwise). Dispatch is class-aware: tool_gate runs evaluate_pre_dispatch + evaluate_post_dispatch, transform runs transform_arguments, identity runs resolve_identity. Without --key the signature check is skipped (dev-only).

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 (the descriptor) plus exactly one of plugin.so / plugin.wasm, and an optional plugin.sig. On a registry it is an OCI 1.1 artifact (artifactType: application/vnd.mcpg.plugin.v1) — docker pull deliberately rejects it; the gateway and mcpg-plugins pull understand it.