CLI Reference¶

Complete command reference for the mpl binary. The MPL CLI provides proxy management, schema operations, payload validation, QoM evaluation, and conformance testing.

Installation¶

HomebrewGo InstallBinary Download

brew install skelf-research/tap/mpl

go install github.com/Skelf-Research/mpl@latest

Download the latest release from the releases page and place the binary in your $PATH.

Global Options¶

These options are available on all commands:

Option	Description
`--verbose`	Enable verbose output (debug-level logging)
`--quiet`	Suppress all non-essential output
`--data-dir <path>`	Override the default data directory (default: `~/.mpl`)

Commands¶

`mpl proxy`¶

Start the MPL proxy server. The proxy sits between your application and the upstream MCP/A2A server, providing schema validation, QoM enforcement, and observability.

mpl proxy <upstream>

Arguments¶

Argument	Description
`<upstream>`	Address of the upstream MCP/A2A server (e.g., `localhost:8080`)

Options¶

Option	Default	Description
`--listen <addr>`	`0.0.0.0:9443`	Address and port for the proxy to listen on
`--mode <mode>`	`transparent`	Proxy enforcement mode: `transparent`, `development`, or `production`
`--learn`	`false`	Enable schema learning from observed traffic
`--schemas <path>`	`./schemas`	Path to the schema directory
`--metrics-port <port>`	`9100`	Port for the Prometheus metrics endpoint
`--config <path>`	`./mpl-config.yaml`	Path to the configuration file

Modes¶

Mode	Behavior
`transparent`	Pass-through with logging only; no blocking
`development`	Validate and warn on violations; log detailed diagnostics
`production`	Enforce all schemas and policies; reject invalid payloads

Examples¶

Start the proxy in transparent mode with default settings:

mpl proxy localhost:8080

Start in production mode with a custom listen address:

mpl proxy localhost:8080 \
  --listen 0.0.0.0:9443 \
  --mode production \
  --schemas ./registry/schemas

Start with schema learning enabled:

mpl proxy localhost:8080 \
  --learn \
  --mode development

Start with a specific config file:

mpl proxy localhost:8080 --config /etc/mpl/mpl-config.yaml

`mpl schemas generate`¶

Generate JSON schemas from observed traffic. Requires that the proxy has been running with --learn enabled and has collected sufficient samples.

mpl schemas generate

Options¶

Option	Default	Description
`--min-samples <n>`	`10`	Minimum number of observed samples required to generate a schema
`--output <path>`	`./schemas`	Output directory for generated schema files

Examples¶

Generate schemas with default settings:

mpl schemas generate

Generate schemas requiring at least 50 samples per SType:

mpl schemas generate --min-samples 50 --output ./registry/schemas

`mpl schemas list`¶

List all known schemas in the registry.

mpl schemas list

Options¶

Option	Default	Description
`--status <status>`	`all`	Filter by status: `pending`, `approved`, or `all`

Examples¶

List all schemas:

mpl schemas list

SType                    Status      Version   Samples
─────────────────────────────────────────────────────
mcp.tool.search          approved    1.2.0     847
mcp.tool.calculate       approved    1.0.0     312
mcp.resource.file        pending     -         28
a2a.task.summarize       pending     -         15

List only pending schemas:

mpl schemas list --status pending

`mpl schemas approve`¶

Approve a pending schema, promoting it to active enforcement.

mpl schemas approve <stype>

Arguments¶

Argument	Description
`<stype>`	The SType identifier to approve (e.g., `mcp.tool.search`)

Options¶

Option	Description
`--all`	Approve all pending schemas at once

Examples¶

Approve a single schema:

mpl schemas approve mcp.tool.search

Approve all pending schemas:

mpl schemas approve --all

`mpl schemas show`¶

Display detailed information about a specific schema, including its JSON Schema definition and metadata.

mpl schemas show <stype>

Arguments¶

Argument	Description
`<stype>`	The SType identifier to display

Examples¶

mpl schemas show mcp.tool.search

SType: mcp.tool.search
Status: approved
Version: 1.2.0
Samples: 847
Hash: sha256:a1b2c3d4...

Schema:
{
  "type": "object",
  "properties": {
    "query": { "type": "string", "minLength": 1 },
    "limit": { "type": "integer", "minimum": 1, "maximum": 100 },
    "filters": {
      "type": "object",
      "properties": {
        "date_range": { "type": "string" }
      }
    }
  },
  "required": ["query"]
}

`mpl schemas export`¶

Export all approved schemas to a portable registry format suitable for distribution or version control.

mpl schemas export

Examples¶

mpl schemas export > registry-export.json

`mpl validate`¶

Validate a JSON payload against a registered SType schema.

mpl validate <payload>

Arguments¶

Argument	Description
`<payload>`	JSON payload string or path to a JSON file (prefix with `@` for file paths)

Options¶

Option	Required	Description
`--stype <stype>`	Yes	The SType to validate against
`--registry <path>`	No	Path to the schema registry (default: `./registry`)

Examples¶

Validate an inline JSON payload:

mpl validate '{"query": "hello", "limit": 10}' --stype mcp.tool.search

Validation: PASSED
SType: mcp.tool.search
Schema version: 1.2.0

Validate from a file:

mpl validate @payload.json --stype mcp.tool.search --registry ./my-registry

Validation failure example:

mpl validate '{"limit": -5}' --stype mcp.tool.search

Validation: FAILED
SType: mcp.tool.search
Errors:
  - $.query: required property missing
  - $.limit: value -5 is less than minimum 1

`mpl hash`¶

Compute the semantic hash of a JSON payload. Semantic hashing normalizes the payload structure before hashing, ensuring equivalent payloads produce identical hashes regardless of key ordering.

mpl hash <payload>

Arguments¶

Argument	Description
`<payload>`	JSON payload string or path to a JSON file (prefix with `@`)

Examples¶

mpl hash '{"query": "hello", "limit": 10}'

sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Hash from a file:

mpl hash @request.json

`mpl qom evaluate`¶

Evaluate Quality of Message (QoM) metrics for a given payload against a QoM profile.

mpl qom evaluate

Options¶

Option	Description
`--profile <name>`	QoM profile to evaluate against (e.g., `qom-basic`, `qom-strict`)
`--payload <json>`	JSON payload to evaluate

Examples¶

Evaluate with the basic profile:

mpl qom evaluate --profile qom-basic --payload '{"query": "summarize this document", "context": "..."}'

QoM Evaluation Results
──────────────────────
Profile: qom-basic
Overall Score: 0.87

Dimensions:
  completeness:    0.92  PASS
  consistency:     0.85  PASS
  specificity:     0.84  PASS
  schema_conform:  1.00  PASS

Verdict: PASS (threshold: 0.80)

Evaluate with a strict profile:

mpl qom evaluate --profile qom-strict --payload @message.json

`mpl init`¶

Initialize a new registry namespace with the default directory structure and configuration files.

mpl init <namespace>

Arguments¶

Argument	Description
`<namespace>`	Namespace identifier (e.g., `my-org.my-project`)

Examples¶

mpl init my-org.my-project

Initialized MPL registry namespace: my-org.my-project
Created:
  ./registry/my-org.my-project/
  ./registry/my-org.my-project/schemas/
  ./registry/my-org.my-project/profiles/
  ./registry/my-org.my-project/policies/
  ./registry/my-org.my-project/manifest.yaml

`mpl conformance`¶

Run conformance tests to verify that schemas, profiles, and policies are correctly configured and that the proxy behaves as expected.

mpl conformance

Options¶

Option	Description
`--registry <path>`	Path to the registry to test (default: `./registry`)
`--filter <pattern>`	Filter tests by glob pattern

Examples¶

Run all conformance tests:

mpl conformance

Running conformance tests...

  ✓ Schema validation: mcp.tool.search (12 cases)
  ✓ Schema validation: mcp.tool.calculate (8 cases)
  ✓ QoM profile: qom-basic (5 cases)
  ✓ QoM profile: qom-strict (5 cases)
  ✓ Policy: rate-limit (3 cases)
  ✓ Policy: content-filter (4 cases)

Results: 37/37 passed

Run only schema-related tests:

mpl conformance --filter "schema.*"

Run tests against a specific registry:

mpl conformance --registry ./staging-registry --filter "mcp.tool.*"

Exit Codes¶

Code	Meaning
`0`	Success
`1`	General error
`2`	Validation failure
`3`	Configuration error
`4`	Connection error (upstream unreachable)
`5`	Schema not found

Environment Variables¶

The CLI respects the following environment variables:

Variable	Description
`MPL_DATA_DIR`	Override the default data directory
`MPL_CONFIG`	Path to the config file
`MPL_UPSTREAM`	Default upstream address
`MPL_MODE`	Default proxy mode
`MPL_LOG_LEVEL`	Log verbosity (`debug`, `info`, `warn`, `error`)
`MPL_METRICS_PORT`	Metrics endpoint port

Shell Completions¶

Generate shell completion scripts:

BashZshFish

mpl completion bash > /etc/bash_completion.d/mpl

mpl completion zsh > "${fpath[1]}/_mpl"

mpl completion fish > ~/.config/fish/completions/mpl.fish

CLI Reference¶

Installation¶

Global Options¶

Commands¶

mpl proxy¶

Arguments¶

Options¶

Modes¶

Examples¶

mpl schemas generate¶

Options¶

Examples¶

mpl schemas list¶

Options¶

Examples¶

mpl schemas approve¶

Arguments¶

Options¶

Examples¶

mpl schemas show¶

Arguments¶

Examples¶

mpl schemas export¶

Examples¶

mpl validate¶

Arguments¶

Options¶

Examples¶

mpl hash¶

Arguments¶

Examples¶

mpl qom evaluate¶

Options¶

Examples¶

mpl init¶

Arguments¶

Examples¶

mpl conformance¶

Options¶

Examples¶

Exit Codes¶

Environment Variables¶

Shell Completions¶

`mpl proxy`¶

`mpl schemas generate`¶

`mpl schemas list`¶

`mpl schemas approve`¶

`mpl schemas show`¶

`mpl schemas export`¶

`mpl validate`¶

`mpl hash`¶

`mpl qom evaluate`¶

`mpl init`¶

`mpl conformance`¶