mtp-sdk
Add MTP --mtp-describe support to any Click CLI. One function call, zero boilerplate.
Install
pip install mtp-sdk click
Quick Start
import click
from mtp_sdk import with_describe, DescribeOptions, CommandAnnotation, Example, IODescriptor
@click.group()
def cli():
"""Convert and validate files"""
@cli.command()
@click.argument("input")
@click.option("--format", default="json", help="Output format")
@click.option("--pretty", is_flag=True, help="Pretty-print output")
def convert(input, format, pretty):
"""Convert a file"""
with_describe(cli, DescribeOptions(
version="1.0.0",
commands={
"convert": CommandAnnotation(
arg_descriptions={"input": "Input file path"},
stdin=IODescriptor(content_type="text/plain", description="Raw input"),
stdout=IODescriptor(content_type="application/json"),
examples=[
Example(description="Convert CSV", command="filetool convert data.csv --format json"),
],
),
},
))
if __name__ == "__main__":
cli()
$ filetool --mtp-describe # MTP JSON schema
$ filetool convert data.csv # normal operation
API
with_describe(cli, options?)
Adds --mtp-describe to an existing Click command or group. When invoked, outputs MTP-compliant JSON and exits.
- cli - a Click
BaseCommandinstance (your root command or group) - options.version - version string for the tool
- options.commands - per-command annotations keyed by command name (stdin, stdout, examples, arg_types, arg_descriptions)
- options.auth - authentication config to include in the schema
- Returns the cli for chaining
describe(cli, options?)
Pure function. Returns the ToolSchema object without side effects. Useful for testing or programmatic access.
How It Works
The SDK introspects Click's own data structures (params, type objects, subcommands) so you never duplicate information. Supplemental metadata (stdin/stdout/examples) that Click doesn't model is provided via the options map.
Type Inference
Arg types describe flags and positional arguments, which are always scalar on the command line:
| Click signal | MTP type |
|---|---|
Option.is_flag |
"boolean" |
click.Choice(...) |
"enum" + values |
Option.multiple / nargs=-1 |
"array" |
click.INT / IntRange |
"integer" |
click.FLOAT / FloatRange |
"number" |
click.BOOL |
"boolean" |
click.Path(...) |
"path" |
Option.count |
"integer" |
explicit arg_types override |
whatever you say |
| everything else | "string" |
For structured data flowing through stdin/stdout, use the schema field in IO descriptors. This supports full JSON Schema (draft 2020-12): nested objects, arrays, unions, pattern validation, conditional fields.
Structured IO
When a command accepts or produces JSON, describe the shape with a JSON Schema:
with_describe(cli, DescribeOptions(
version="1.0.0",
commands={
"process": CommandAnnotation(
stdin=IODescriptor(
content_type="application/json",
description="Configuration to process",
schema={
"type": "object",
"properties": {
"name": {"type": "string"},
"settings": {
"type": "object",
"properties": {
"retries": {"type": "integer"},
"endpoints": {
"type": "array",
"items": {"type": "string", "format": "uri"},
},
},
},
},
"required": ["name"],
},
),
stdout=IODescriptor(
content_type="application/json",
schema={
"type": "object",
"properties": {
"status": {"type": "string", "enum": ["ok", "error"]},
"results": {"type": "array", "items": {"type": "object"}},
},
},
),
),
},
))
### Command Naming
- Groups with subcommands: each leaf command gets a space-separated path (e.g., `"auth login"`)
- Commands with no subcommands: single command named `"_root"`
- Hidden commands and options are excluded
### Argument Descriptions
Click arguments don't support `help` text natively. Use `arg_descriptions` in your annotation:
```python
CommandAnnotation(
arg_descriptions={"input_file": "Input file path"},
)
Filtered Options
These are automatically excluded from schema output: --help, --version, --mtp-describe, and any hidden options.
Single-Command Tools
Tools with no subcommands work the same way:
import click
from mtp_sdk import with_describe, DescribeOptions
@click.command()
@click.argument("name")
@click.option("--loud", is_flag=True, help="Shout the greeting")
def greet(name, loud):
"""Greet someone"""
msg = f"Hello, {name}!"
click.echo(msg.upper() if loud else msg)
with_describe(greet, DescribeOptions(version="1.0.0"))
if __name__ == "__main__":
greet()
This produces a schema with a single _root command.
Metadata
Release files for mtp-sdk 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mtp_sdk-0.3.0.tar.gz | 13.4 kB | Without provenance | Details for mtp_sdk-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mtp_sdk-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for mtp_sdk-0.3.0-py3-none-any.whl |
Total release size: 24.2 kB
Release files / mtp_sdk-0.3.0.tar.gz
| Download URL | mtp_sdk-0.3.0.tar.gz |
|---|---|
| Size | 13.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8fe61fdec730cfa9fc27ebfc35835e658854bf40ac47f4d1dcc25476474fe1dd
|
|
BLAKE2b-256 checksum How to use checksums |
6a80fb60d78b0337ee8e722e357c85d98dae62ca86855cc436884eb1f7247768
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / mtp_sdk-0.3.0-py3-none-any.whl
| Download URL | mtp_sdk-0.3.0-py3-none-any.whl |
|---|---|
| Size | 10.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
14eaaa4b5bad0c115019fb1390673d39e3301a7b30fa8953ed1d0b780710ebd4
|
|
BLAKE2b-256 checksum How to use checksums |
c12fb9b31336334309f1b3c0bee7d0048786b091815006b4fc58dbc5153513f2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for mtp-sdk 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.