Skip to main content

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 BaseCommand instance (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)

Source distribution for mtp-sdk 0.3.0
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)

Table of built distributions (wheels) for mtp-sdk 0.3.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page