monxcli 1.0.2
A simple, extensible git like CLI framework.
License: MIT
Requires Python: >=3.7

# monxcli



## Getting started

an arg parser decorator to simplify argument parsing


## Name
monxcli

## Description
"A lightweight and extensible CLI framework for building modular, Git-like command-line tools. Simplify command grouping, subcommand handling, and argument parsing with a decorator-based approach."


## Usage
the following structure should be use. Scripts are group according to modules
```
<folder>/
        + <folder>/
            - yourscript.py
        main.py

example
monxcli
├── monxcli/
├── main.py
├── mc <-- example scripts are in this module 
│   ├── __init__.py
│   └── math_commands.py
```
### using the decorator example:

MonxCLI integrates with `fastmcp` to seamlessly expose your CLI commands as AI-callable tools, prompts, and resources. This is achieved using specialized decorators.

#### Exposing Commands as `mcp.tool` with `@monx_tool`

Import `monx_tool` from `monxcli.mcp_bridge` and use it to define your CLI commands. This decorator automatically registers your functions with both the MonxCLI command parser and the `fastmcp` server as an `mcp.tool`. The function's docstring and type hints are used to generate the tool's description and schema for AI systems.

For example, the `mc_example/math_commands.py` file defines math operations:

```python
from monxcli.mcp_bridge import monx_tool


@monx_tool(desc="Add two numbers together.")
@staticmethod
def add(x: int, y: int):
    """Adds two numbers."""
    print(f"The result of {x} + {y} is {x + y}")

@monx_tool(desc="subtract two numbers.")
@staticmethod
def subtract(x: int, y: int):
    """Subtracts two numbers."""
    print(f"The result of {x} - {y} is {x - y}")

@monx_tool(desc="Multiply two numbers.")
@staticmethod
def multiply(a: int, b: int):
    return a * b

@monx_tool(desc="Divide two numbers.")
@staticmethod
def divide(a: int, b: int):
    """Divides two numbers."""
    if b == 0:
        raise ValueError("Cannot divide by zero.")
    return a / b
```

#### Exposing Prompts as `mcp.prompt` with `@monx_prompt`

The `@monx_prompt` decorator is used to define reusable prompt templates for Large Language Models (LLMs). These prompts also become callable MonxCLI commands.

For example, the `monxcli/prompts.py` file demonstrates:

```python
from monxcli.mcp_bridge import monx_prompt

@monx_prompt(desc="Generates a prompt to summarize a given document.")
def summarize_document(document_text: str, length: str = "short"):
    """
    Generates a prompt to summarize a given document.
    The length can be 'short', 'medium', or 'long'.
    """
    if length == "short":
        return f"Please provide a concise summary of the following document:\n\n{document_text}"
    elif length == "medium":
        return f"Summarize the key points of the following document:\n\n{document_text}"
    else:
        return f"Provide a detailed summary of the following document, including all important aspects:\n\n{document_text}"

@monx_prompt(desc="Generates a prompt to translate text to a target language.")
def translate_text(text: str, target_language: str):
    """
    Generates a prompt to translate text to a target language.
    """
    return f"Translate the following text to {target_language}:\n\n{text}"
```

#### Exposing Data as `mcp.resource` with `@monx_resource`

The `@monx_resource` decorator exposes data as resources that AI assistants can access, and also registers them as MonxCLI commands.

For example, the `monxcli/resources.py` file demonstrates:

```python
from monxcli.mcp_bridge import monx_resource

@monx_resource(desc="Provides a list of languages supported for translation.")
def available_languages():
    """
    Provides a list of languages supported for translation.
    """
    return ["English", "Spanish", "French", "German", "Italian", "Portuguese"]

@monx_resource(desc="Retrieves user-specific preferences.")
def get_user_preferences(user_id: str):
    """
    Retrieves user-specific preferences.
    """
    # In a real application, this would fetch data from a database or API
    preferences = {
        "user123": {"theme": "dark", "notifications": True},
        "user456": {"theme": "light", "notifications": False},
    }
    return preferences.get(user_id, {"theme": "system", "notifications": True})
```

To activate the CLI, your main function should just import the modules where the commands are defined. Monxcli will take of the rest.

```
from mc import math_commands  # just import your module/script here

from monxcli.commands import commands  # Shared LazyCommandParser


if __name__ == "__main__":
    # Execute commands only if the script is run as the main module
    commands()
```

running the main script example:
```
> python3 main.py mc math_commands add --x 3 --y 3
```

mc is the folder or module and math_commands is the submodule, 'add' is the function you want to call then --x and --y are the arguments passed to your functions.

result:
```
$ python3 main.py mc math_commands add --x 3 --y 3
The result of 3 + 3 is 6
```
## Support
contact author https://gitlab.com/mongkoy/


## Project status
on-going