mtp-sdk 0.1.1

Add MTP --describe support to any Click CLI

mtp-sdk

Add 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 --describe          # MTP JSON schema
$ filetool convert data.csv    # normal operation

API

with_describe(cli, options?)

Adds --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

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"

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:

CommandAnnotation(
    arg_descriptions={"input_file": "Input file path"},
)

Filtered Options

These are automatically excluded from schema output: --help, --version, --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.