Skip to content

BaseToolCLI

BaseToolCLI

Bases: ABC

Base class for tool CLIs.

Provides a standard interface so every MCPStack tool can ship a consistent, discoverable CLI that plugs into the global mcpstack tools <name> ... namespace.

Why a CLI?

MCPStack tools are both programmable and operable via CLI. The CLI is great for quick inspection, local setup, status checks, and generating config that can later be loaded programmatically.

Required responsibilities
  • expose a Typer app via :meth:get_app
  • implement first-time setup :meth:init
  • provide configuration via :meth:configure
  • display human-readable status via :meth:status

Keep it non-interactive by default

Prefer flags/options over interactive prompts so the CLI is easy to automate in CI scripts.

Source code in src/MCPStack/core/tool/cli/base.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
@beartype
class BaseToolCLI(ABC):
    """Base class for tool CLIs.

    Provides a standard interface so every MCPStack tool can ship a consistent,
    discoverable CLI that plugs into the global `mcpstack tools <name> ...`
    namespace.

    !!! note "Why a CLI?"
        MCPStack tools are both **programmable** and **operable via CLI**.
        The CLI is great for quick inspection, local setup, status checks,
        and generating config that can later be loaded programmatically.

    Required responsibilities:
      * expose a Typer app via :meth:`get_app`
      * implement first-time setup :meth:`init`
      * provide configuration via :meth:`configure`
      * display human-readable status via :meth:`status`

    !!! tip "Keep it non-interactive by default"
        Prefer flags/options over interactive prompts so the CLI is easy to
        automate in CI scripts.
    """

    @classmethod
    @abstractmethod
    def get_app(cls) -> typer.Typer:
        """Return the `typer.Typer` app that defines the tool subcommands.

        The returned app will be mounted under `mcpstack tools <tool-name>`.
        Define commands like `init`, `configure`, `status`, or any
        tool-specific operations.

        Returns:
            typer.Typer: A fully configured Typer application.

        !!! example "Minimal Typer app"
            ```python
            import typer

            @classmethod
            def get_app(cls) -> typer.Typer:
                app = typer.Typer(help="MyTool CLI")

                @app.command()
                def ping():
                    '''Quick health check.'''
                    typer.echo("pong")

                return app
            ```
        """
        ...

    @classmethod
    @abstractmethod
    def init(cls, *args: Any, **kwargs: Any) -> None:
        """Perform first-time setup for the tool.

        Use this to create local directories (if needed), warm caches, or write template
        config files. This method should be **idempotent**.

        Args:
            *args: Implementation-defined positional arguments.
            **kwargs: Implementation-defined keyword arguments.
        """
        ...

    @classmethod
    @abstractmethod
    def configure(cls) -> ToolConfig:
        """Return a `ToolConfig` payload with env vars and tool params.

        This is typically used by the top-level CLI to merge environment
        variables and pass parameters into the tool is `from_dict(...)`.

        Returns:
            ToolConfig: A mapping with `env_vars` and `tool_params`.

        !!! warning "Do not include secrets you cannot verify"
            Only include env vars the user opted into or that you can read from
            the current process environment.
        """
        ...

    @classmethod
    @abstractmethod
    def status(cls, *args: Any, **kwargs: Any) -> None:
        """Print human-readable status for diagnostics.

        Show effective env values (mask secrets), key configuration, and any
        external service connectivity checks. Output should be concise and
        suitable for terminals.

        Args:
            *args: Implementation-defined positional arguments.
            **kwargs: Implementation-defined keyword arguments.

        !!! note "Be careful with secrets"
            Mask tokens and passwords by default (e.g., show last 4 chars).
        """
        ...

configure() abstractmethod classmethod

Return a ToolConfig payload with env vars and tool params.

This is typically used by the top-level CLI to merge environment variables and pass parameters into the tool is from_dict(...).

Returns:

Name Type Description
ToolConfig ToolConfig

A mapping with env_vars and tool_params.

Do not include secrets you cannot verify

Only include env vars the user opted into or that you can read from the current process environment.

Source code in src/MCPStack/core/tool/cli/base.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
@classmethod
@abstractmethod
def configure(cls) -> ToolConfig:
    """Return a `ToolConfig` payload with env vars and tool params.

    This is typically used by the top-level CLI to merge environment
    variables and pass parameters into the tool is `from_dict(...)`.

    Returns:
        ToolConfig: A mapping with `env_vars` and `tool_params`.

    !!! warning "Do not include secrets you cannot verify"
        Only include env vars the user opted into or that you can read from
        the current process environment.
    """
    ...

get_app() abstractmethod classmethod

Return the typer.Typer app that defines the tool subcommands.

The returned app will be mounted under mcpstack tools <tool-name>. Define commands like init, configure, status, or any tool-specific operations.

Returns:

Type Description
Typer

typer.Typer: A fully configured Typer application.

Minimal Typer app

import typer

@classmethod
def get_app(cls) -> typer.Typer:
    app = typer.Typer(help="MyTool CLI")

    @app.command()
    def ping():
        '''Quick health check.'''
        typer.echo("pong")

    return app
Source code in src/MCPStack/core/tool/cli/base.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
@abstractmethod
def get_app(cls) -> typer.Typer:
    """Return the `typer.Typer` app that defines the tool subcommands.

    The returned app will be mounted under `mcpstack tools <tool-name>`.
    Define commands like `init`, `configure`, `status`, or any
    tool-specific operations.

    Returns:
        typer.Typer: A fully configured Typer application.

    !!! example "Minimal Typer app"
        ```python
        import typer

        @classmethod
        def get_app(cls) -> typer.Typer:
            app = typer.Typer(help="MyTool CLI")

            @app.command()
            def ping():
                '''Quick health check.'''
                typer.echo("pong")

            return app
        ```
    """
    ...

init(*args, **kwargs) abstractmethod classmethod

Perform first-time setup for the tool.

Use this to create local directories (if needed), warm caches, or write template config files. This method should be idempotent.

Parameters:

Name Type Description Default
*args Any

Implementation-defined positional arguments.

 ()
**kwargs Any

Implementation-defined keyword arguments.

 {}
Source code in src/MCPStack/core/tool/cli/base.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
@classmethod
@abstractmethod
def init(cls, *args: Any, **kwargs: Any) -> None:
    """Perform first-time setup for the tool.

    Use this to create local directories (if needed), warm caches, or write template
    config files. This method should be **idempotent**.

    Args:
        *args: Implementation-defined positional arguments.
        **kwargs: Implementation-defined keyword arguments.
    """
    ...

status(*args, **kwargs) abstractmethod classmethod

Print human-readable status for diagnostics.

Show effective env values (mask secrets), key configuration, and any external service connectivity checks. Output should be concise and suitable for terminals.

Parameters:

Name Type Description Default
*args Any

Implementation-defined positional arguments.

 ()
**kwargs Any

Implementation-defined keyword arguments.

 {}

Be careful with secrets

Mask tokens and passwords by default (e.g., show last 4 chars).

Source code in src/MCPStack/core/tool/cli/base.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
@classmethod
@abstractmethod
def status(cls, *args: Any, **kwargs: Any) -> None:
    """Print human-readable status for diagnostics.

    Show effective env values (mask secrets), key configuration, and any
    external service connectivity checks. Output should be concise and
    suitable for terminals.

    Args:
        *args: Implementation-defined positional arguments.
        **kwargs: Implementation-defined keyword arguments.

    !!! note "Be careful with secrets"
        Mask tokens and passwords by default (e.g., show last 4 chars).
    """
    ...