utcp-cli 1.0.0__tar.gz → 1.0.2__tar.gz

utcp_cli-1.0.2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: utcp-cli
+Version: 1.0.2
+Summary: UTCP communication protocol plugin for wrapping local command-line tools.
+Author: UTCP Contributors
+License-Expression: MPL-2.0
+Project-URL: Homepage, https://utcp.io
+Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
+Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: utcp>=1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# UTCP CLI Plugin
+
+[![PyPI Downloads](https://static.pepy.tech/badge/utcp-cli)](https://pepy.tech/projects/utcp-cli)
+
+Command-line interface plugin for UTCP, enabling integration with command-line tools and processes.
+
+## Features
+
+- **Command Execution**: Run any command-line tool as a UTCP tool
+- **Environment Variables**: Secure credential and configuration passing
+- **Working Directory Control**: Execute commands in specific directories
+- **Input/Output Handling**: Support for stdin, stdout, stderr processing
+- **Cross-Platform**: Works on Windows, macOS, and Linux
+- **Timeout Management**: Configurable execution timeouts
+- **Argument Validation**: Optional input sanitization
+
+## Installation
+
+```bash
+pip install utcp-cli
+```
+
+## Quick Start
+
+```python
+from utcp.utcp_client import UtcpClient
+
+# Basic CLI tool
+client = await UtcpClient.create(config={
+    "manual_call_templates": [{
+        "name": "file_tools",
+        "call_template_type": "cli",
+        "command_name": "ls -la ${path}"
+    }]
+})
+
+result = await client.call_tool("file_tools.list", {"path": "/home"})
+```
+
+## Configuration Examples
+
+### Basic Command
+```json
+{
+  "name": "file_ops",
+  "call_template_type": "cli",
+  "command_name": "ls -la ${path}",
+  "working_dir": "/tmp"
+}
+```
+
+### With Environment Variables
+```json
+{
+  "name": "python_script",
+  "call_template_type": "cli",
+  "command_name": "python script.py ${input}",
+  "env_vars": {
+    "PYTHONPATH": "/custom/path",
+    "API_KEY": "${API_KEY}"
+  }
+}
+```
+
+### Processing JSON with jq
+```json
+{
+  "name": "json_processor",
+  "call_template_type": "cli",
+  "command_name": "jq '.data'",
+  "stdin": "${json_input}",
+  "timeout": 10
+}
+```
+
+### Git Operations
+```json
+{
+  "name": "git_tools",
+  "call_template_type": "cli",
+  "command_name": "git ${operation} ${args}",
+  "working_dir": "${repo_path}",
+  "env_vars": {
+    "GIT_AUTHOR_NAME": "${author_name}",
+    "GIT_AUTHOR_EMAIL": "${author_email}"
+  }
+}
+```
+
+## Security Considerations
+
+- Commands run in isolated subprocesses
+- Environment variables provide secure credential passing
+- Working directory restrictions limit file system access
+- Input validation prevents command injection
+
+```json
+{
+  "name": "safe_grep",
+  "call_template_type": "cli",
+  "command_name": "grep ${pattern} ${file}",
+  "working_dir": "/safe/directory",
+  "allowed_args": {
+    "pattern": "^[a-zA-Z0-9_-]+$",
+    "file": "^[a-zA-Z0-9_./-]+\\.txt$"
+  }
+}
+```
+
+## Error Handling
+
+```python
+from utcp.exceptions import ToolCallError
+import subprocess
+
+try:
+    result = await client.call_tool("cli_tool.command", {"arg": "value"})
+except ToolCallError as e:
+    if isinstance(e.__cause__, subprocess.CalledProcessError):
+        print(f"Command failed with exit code {e.__cause__.returncode}")
+        print(f"stderr: {e.__cause__.stderr}")
+```
+
+## Common Use Cases
+
+- **File Operations**: ls, find, grep, awk, sed
+- **Data Processing**: jq, sort, uniq, cut
+- **System Monitoring**: ps, top, df, netstat
+- **Development Tools**: git, npm, pip, docker
+- **Custom Scripts**: Python, bash, PowerShell scripts
+
+## Testing CLI Tools
+
+```python
+import pytest
+from utcp.utcp_client import UtcpClient
+
+@pytest.mark.asyncio
+async def test_cli_tool():
+    client = await UtcpClient.create(config={
+        "manual_call_templates": [{
+            "name": "test_cli",
+            "call_template_type": "cli",
+            "command_name": "echo ${message}"
+        }]
+    })
+    
+    result = await client.call_tool("test_cli.echo", {"message": "hello"})
+    assert "hello" in result["stdout"]
+```
+
+## Related Documentation
+
+- [Main UTCP Documentation](../../../README.md)
+- [Core Package Documentation](../../../core/README.md)
+- [HTTP Plugin](../http/README.md)
+- [MCP Plugin](../mcp/README.md)
+- [Text Plugin](../text/README.md)
+
+## Examples
+
+For complete examples, see the [UTCP examples repository](https://github.com/universal-tool-calling-protocol/utcp-examples).

utcp_cli-1.0.2/README.md

@@ -0,0 +1,162 @@
+# UTCP CLI Plugin
+
+[![PyPI Downloads](https://static.pepy.tech/badge/utcp-cli)](https://pepy.tech/projects/utcp-cli)
+
+Command-line interface plugin for UTCP, enabling integration with command-line tools and processes.
+
+## Features
+
+- **Command Execution**: Run any command-line tool as a UTCP tool
+- **Environment Variables**: Secure credential and configuration passing
+- **Working Directory Control**: Execute commands in specific directories
+- **Input/Output Handling**: Support for stdin, stdout, stderr processing
+- **Cross-Platform**: Works on Windows, macOS, and Linux
+- **Timeout Management**: Configurable execution timeouts
+- **Argument Validation**: Optional input sanitization
+
+## Installation
+
+```bash
+pip install utcp-cli
+```
+
+## Quick Start
+
+```python
+from utcp.utcp_client import UtcpClient
+
+# Basic CLI tool
+client = await UtcpClient.create(config={
+    "manual_call_templates": [{
+        "name": "file_tools",
+        "call_template_type": "cli",
+        "command_name": "ls -la ${path}"
+    }]
+})
+
+result = await client.call_tool("file_tools.list", {"path": "/home"})
+```
+
+## Configuration Examples
+
+### Basic Command
+```json
+{
+  "name": "file_ops",
+  "call_template_type": "cli",
+  "command_name": "ls -la ${path}",
+  "working_dir": "/tmp"
+}
+```
+
+### With Environment Variables
+```json
+{
+  "name": "python_script",
+  "call_template_type": "cli",
+  "command_name": "python script.py ${input}",
+  "env_vars": {
+    "PYTHONPATH": "/custom/path",
+    "API_KEY": "${API_KEY}"
+  }
+}
+```
+
+### Processing JSON with jq
+```json
+{
+  "name": "json_processor",
+  "call_template_type": "cli",
+  "command_name": "jq '.data'",
+  "stdin": "${json_input}",
+  "timeout": 10
+}
+```
+
+### Git Operations
+```json
+{
+  "name": "git_tools",
+  "call_template_type": "cli",
+  "command_name": "git ${operation} ${args}",
+  "working_dir": "${repo_path}",
+  "env_vars": {
+    "GIT_AUTHOR_NAME": "${author_name}",
+    "GIT_AUTHOR_EMAIL": "${author_email}"
+  }
+}
+```
+
+## Security Considerations
+
+- Commands run in isolated subprocesses
+- Environment variables provide secure credential passing
+- Working directory restrictions limit file system access
+- Input validation prevents command injection
+
+```json
+{
+  "name": "safe_grep",
+  "call_template_type": "cli",
+  "command_name": "grep ${pattern} ${file}",
+  "working_dir": "/safe/directory",
+  "allowed_args": {
+    "pattern": "^[a-zA-Z0-9_-]+$",
+    "file": "^[a-zA-Z0-9_./-]+\\.txt$"
+  }
+}
+```
+
+## Error Handling
+
+```python
+from utcp.exceptions import ToolCallError
+import subprocess
+
+try:
+    result = await client.call_tool("cli_tool.command", {"arg": "value"})
+except ToolCallError as e:
+    if isinstance(e.__cause__, subprocess.CalledProcessError):
+        print(f"Command failed with exit code {e.__cause__.returncode}")
+        print(f"stderr: {e.__cause__.stderr}")
+```
+
+## Common Use Cases
+
+- **File Operations**: ls, find, grep, awk, sed
+- **Data Processing**: jq, sort, uniq, cut
+- **System Monitoring**: ps, top, df, netstat
+- **Development Tools**: git, npm, pip, docker
+- **Custom Scripts**: Python, bash, PowerShell scripts
+
+## Testing CLI Tools
+
+```python
+import pytest
+from utcp.utcp_client import UtcpClient
+
+@pytest.mark.asyncio
+async def test_cli_tool():
+    client = await UtcpClient.create(config={
+        "manual_call_templates": [{
+            "name": "test_cli",
+            "call_template_type": "cli",
+            "command_name": "echo ${message}"
+        }]
+    })
+    
+    result = await client.call_tool("test_cli.echo", {"message": "hello"})
+    assert "hello" in result["stdout"]
+```
+
+## Related Documentation
+
+- [Main UTCP Documentation](../../../README.md)
+- [Core Package Documentation](../../../core/README.md)
+- [HTTP Plugin](../http/README.md)
+- [MCP Plugin](../mcp/README.md)
+- [Text Plugin](../text/README.md)
+
+## Examples
+
+For complete examples, see the [UTCP examples repository](https://github.com/universal-tool-calling-protocol/utcp-examples).

{utcp_cli-1.0.0 → utcp_cli-1.0.2}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "utcp-cli"
-version = "1.0.0"
+version = "1.0.2"
 authors = [
   { name = "UTCP Contributors" },
 ]
-description = "Universal Tool Calling Protocol (UTCP) client library for Python"
+description = "UTCP communication protocol plugin for wrapping local command-line tools."
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [

utcp_cli-1.0.2/src/utcp_cli/cli_call_template.py

@@ -0,0 +1,110 @@
+from typing import Optional, Dict, Literal
+from pydantic import Field
+
+from utcp.data.call_template import CallTemplate
+from utcp.interfaces.serializer import Serializer
+from utcp.exceptions import UtcpSerializerValidationError
+import traceback
+
+class CliCallTemplate(CallTemplate):
+    """REQUIRED
+    Call template configuration for Command Line Interface (CLI) tools.
+
+    This class defines the configuration for executing command-line tools and
+    programs as UTCP tool providers. It supports environment variable injection,
+    custom working directories, and defines the command to be executed.
+
+    Attributes:
+        call_template_type: The type of the call template. Must be "cli".
+        command_name: The command or path of the program to execute. It can
+            contain placeholders for arguments that will be substituted at
+            runtime (e.g., `${arg_name}`).
+        env_vars: A dictionary of environment variables to set for the command's
+            execution context. Values can be static strings or placeholders for
+            variables from the UTCP client's variable substitutor.
+        working_dir: The working directory from which to run the command. If not
+            provided, it defaults to the current process's working directory.
+        auth: Authentication details. Not applicable to the CLI protocol, so it
+            is always None.
+
+    Examples:
+        Basic CLI command:
+        ```json
+        {
+          "name": "list_files_tool",
+          "call_template_type": "cli",
+          "command_name": "ls -la",
+          "working_dir": "/tmp"
+        }
+        ```
+
+        Command with environment variables and argument placeholders:
+        ```json
+        {
+          "name": "python_script_tool",
+          "call_template_type": "cli",
+          "command_name": "python script.py --input ${input_file}",
+          "env_vars": {
+            "PYTHONPATH": "/custom/path",
+            "API_KEY": "${API_KEY_VAR}"
+          }
+        }
+        ```
+
+    Security Considerations:
+        - Commands are executed in a subprocess. Ensure that the commands
+          specified are from a trusted source.
+        - Avoid passing unsanitized user input directly into the command string.
+          Use tool argument validation where possible.
+    """
+
+    call_template_type: Literal["cli"] = "cli"
+    command_name: str
+    env_vars: Optional[Dict[str, str]] = Field(
+        default=None, description="Environment variables to set when executing the command"
+    )
+    working_dir: Optional[str] = Field(
+        default=None, description="Working directory for command execution"
+    )
+    auth: None = None
+
+
+class CliCallTemplateSerializer(Serializer[CliCallTemplate]):
+    """REQUIRED
+    Serializer for converting between `CliCallTemplate` and dictionary representations.
+
+    This class handles the serialization and deserialization of `CliCallTemplate`
+    objects, ensuring that they can be correctly represented as dictionaries and
+    reconstructed from them, with validation.
+    """
+
+    def to_dict(self, obj: CliCallTemplate) -> dict:
+        """REQUIRED
+        Converts a `CliCallTemplate` instance to its dictionary representation.
+
+        Args:
+            obj: The `CliCallTemplate` instance to serialize.
+
+        Returns:
+            A dictionary representing the `CliCallTemplate`.
+        """
+        return obj.model_dump()
+
+    def validate_dict(self, obj: dict) -> CliCallTemplate:
+        """REQUIRED
+        Validates a dictionary and constructs a `CliCallTemplate` instance.
+
+        Args:
+            obj: The dictionary to validate and deserialize.
+
+        Returns:
+            A `CliCallTemplate` instance.
+
+        Raises:
+            UtcpSerializerValidationError: If the dictionary is not a valid
+                representation of a `CliCallTemplate`.
+        """
+        try:
+            return CliCallTemplate.model_validate(obj)
+        except Exception as e:
+            raise UtcpSerializerValidationError("Invalid CliCallTemplate: " + traceback.format_exc()) from e

{utcp_cli-1.0.0 → utcp_cli-1.0.2}/src/utcp_cli/cli_communication_protocol.py

@@ -1,28 +1,27 @@
-"""Command Line Interface (CLI) transport for UTCP client.
+"""Command Line Interface (CLI) communication protocol for the UTCP client.
 
-This module provides the CLI transport implementation that enables UTCP clients
-to interact with command-line tools and processes. It handles tool discovery
-through startup commands, tool execution with proper argument formatting,
-and output processing with JSON parsing capabilities.
+This module provides an implementation of the `CommunicationProtocol` interface
+that enables the UTCP client to interact with command-line tools. It supports
+discovering tools by executing a command and parsing its output for a UTCP
+manual, as well as calling those tools with arguments.
 
 Key Features:
-    - Asynchronous command execution with timeout handling
-    - Tool discovery via startup commands that output UTCP manuals
-    - Flexible argument formatting for command-line flags
-    - Environment variable support for authentication and configuration
-    - JSON output parsing with fallback to raw text
-    - Cross-platform command parsing (Windows/Unix)
-    - Working directory control for command execution
-
-Security:
-    - Command execution is isolated through subprocess
-    - Environment variables can be controlled per provider
-    - Working directory can be restricted
+    - Asynchronous execution of shell commands.
+    - Tool discovery by running a command that outputs a UTCP manual.
+    - Flexible argument formatting for different CLI conventions.
+    - Support for environment variables and custom working directories.
+    - Automatic parsing of JSON output with a fallback to raw text.
+    - Cross-platform command parsing for Windows and Unix-like systems.
+
+Security Considerations:
+    Executing arbitrary command-line tools can be dangerous. This protocol
+    should only be used with trusted tools.
 """
 import asyncio
 import json
 import os
 import shlex
+import sys
 from typing import Dict, Any, List, Optional, Callable, AsyncGenerator
 
 from utcp.interfaces.communication_protocol import CommunicationProtocol
@@ -33,37 +32,26 @@ from utcp.data.register_manual_response import RegisterManualResult
 from utcp_cli.cli_call_template import CliCallTemplate, CliCallTemplateSerializer
 import logging
 
-logger = logging.getLogger(__name__)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(filename)s:%(lineno)d - %(message)s"
+)
 
+logger = logging.getLogger(__name__)
 
 class CliCommunicationProtocol(CommunicationProtocol):
-    """Transport implementation for CLI-based tool providers.
-
-    Handles communication with command-line tools by executing processes
-    and managing their input/output. Supports both tool discovery and
-    execution phases with comprehensive error handling and timeout management.
-
-    Features:
-        - Asynchronous subprocess execution with proper cleanup
-        - Tool discovery through startup commands returning UTCP manuals
-        - Flexible argument formatting for various CLI conventions
-        - Environment variable injection for authentication
-        - JSON output parsing with graceful fallback to text
-        - Cross-platform command parsing and execution
-        - Configurable working directories and timeouts
-        - Process lifecycle management with proper termination
-
-    Architecture:
-        CLI tools are discovered by executing the provider's command_name
-        and parsing the output for UTCP manual JSON. Tool calls execute
-        the same command with formatted arguments and return processed output.
-
-    Attributes:
-        _log: Logger function for debugging and error reporting.
+    """REQUIRED
+    Communication protocol for interacting with CLI-based tool providers.
+
+    This class implements the `CommunicationProtocol` interface to handle
+    communication with command-line tools. It discovers tools by executing a
+    command specified in a `CliCallTemplate` and parsing the output for a UTCP
+    manual. It also executes tool calls by running the corresponding command
+    with the provided arguments.
     """
     
     def __init__(self):
-        """Initialize the CLI transport."""
+        """Initializes the `CliCommunicationProtocol`."""
     
     def _log_info(self, message: str):
         """Log informational messages."""
@@ -154,9 +142,25 @@ class CliCommunicationProtocol(CommunicationProtocol):
             raise
     
     async def register_manual(self, caller, manual_call_template: CallTemplate) -> RegisterManualResult:
-        """Register a CLI manual and discover its tools.
-        
-        Executes the call template's command_name and looks for a UTCP manual JSON in the output.
+        """REQUIRED
+        Registers a CLI-based manual and discovers its tools.
+
+        This method executes the command specified in the `CliCallTemplate`'s
+        `command_name` field. It then attempts to parse the command's output
+        (stdout) as a UTCP manual in JSON format.
+
+        Args:
+            caller: The UTCP client instance that is calling this method.
+            manual_call_template: The `CliCallTemplate` containing the details for
+                tool discovery, such as the command to run.
+
+        Returns:
+            A `RegisterManualResult` object indicating whether the registration
+            was successful and containing the discovered tools.
+
+        Raises:
+            ValueError: If the `manual_call_template` is not an instance of
+                `CliCallTemplate` or if `command_name` is not set.
         """
         if not isinstance(manual_call_template, CliCallTemplate):
             raise ValueError("CliCommunicationProtocol can only be used with CliCallTemplate")
@@ -193,7 +197,7 @@ class CliCommunicationProtocol(CommunicationProtocol):
                 return RegisterManualResult(
                     success=False,
                     manual_call_template=manual_call_template,
-                    manual=UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=[]),
+                    manual=UtcpManual(manual_version="0.0.0", tools=[]),
                     errors=[
                         f"No output from discovery command for CLI provider '{manual_call_template.name}'"
                     ],
@@ -212,7 +216,7 @@ class CliCommunicationProtocol(CommunicationProtocol):
                 return RegisterManualResult(
                     success=False,
                     manual_call_template=manual_call_template,
-                    manual=UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=[]),
+                    manual=UtcpManual(manual_version="0.0.0", tools=[]),
                     errors=[error_msg],
                 )
 
@@ -232,12 +236,21 @@ class CliCommunicationProtocol(CommunicationProtocol):
             return RegisterManualResult(
                 success=False,
                 manual_call_template=manual_call_template,
-                manual=UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=[]),
+                manual=UtcpManual(manual_version="0.0.0", tools=[]),
                 errors=[error_msg],
             )
     
     async def deregister_manual(self, caller, manual_call_template: CallTemplate) -> None:
-        """Deregister a CLI manual (no-op)."""
+        """REQUIRED
+        Deregisters a CLI manual.
+
+        For the CLI protocol, this is a no-op as there are no persistent
+        connections to terminate.
+
+        Args:
+            caller: The UTCP client instance that is calling this method.
+            manual_call_template: The call template of the manual to deregister.
+        """
         if isinstance(manual_call_template, CliCallTemplate):
             self._log_info(
                 f"Deregistering CLI manual '{manual_call_template.name}' (no-op)"
@@ -285,12 +298,12 @@ class CliCommunicationProtocol(CommunicationProtocol):
                     # Fallback: try to parse tools from possibly-legacy structure
                     tools = self._parse_tool_data(data, provider_name)
                     if tools:
-                        return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=tools)
+                        return UtcpManual(manual_version="0.0.0", tools=tools)
                     return None
             # Fallback: try to parse as tools
             tools = self._parse_tool_data(data, provider_name)
             if tools:
-                return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=tools)
+                return UtcpManual(manual_version="0.0.0", tools=tools)
         except json.JSONDecodeError:
             pass
 
@@ -313,7 +326,7 @@ class CliCommunicationProtocol(CommunicationProtocol):
                             # Fallback: try to parse tools from possibly-legacy structure
                             tools = self._parse_tool_data(data, provider_name)
                             if tools:
-                                return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=tools)
+                                return UtcpManual(manual_version="0.0.0", tools=tools)
                             return None
                     found_tools = self._parse_tool_data(data, provider_name)
                     aggregated_tools.extend(found_tools)
@@ -321,7 +334,7 @@ class CliCommunicationProtocol(CommunicationProtocol):
                     continue
 
         if aggregated_tools:
-            return UtcpManual(utcp_version="1.0.0", manual_version="0.0.0", tools=aggregated_tools)
+            return UtcpManual(manual_version="0.0.0", tools=aggregated_tools)
 
         return None
     
@@ -399,23 +412,28 @@ class CliCommunicationProtocol(CommunicationProtocol):
         return tools
     
     async def call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> Any:
-        """Call a CLI tool.
-        
-        Executes the command specified by provider.command_name with the provided arguments.
-        
+        """REQUIRED
+        Calls a CLI tool by executing its command.
+
+        This method constructs and executes the command specified in the
+        `CliCallTemplate`. It formats the provided `tool_args` as command-line
+        arguments and runs the command in a subprocess.
+
         Args:
-            caller: The UTCP client that is calling this method.
-            tool_name: Name of the tool to call
-            tool_args: Arguments for the tool call
-            tool_call_template: The CliCallTemplate for the tool
-            
+            caller: The UTCP client instance that is calling this method.
+            tool_name: The name of the tool to call.
+            tool_args: A dictionary of arguments for the tool call.
+            tool_call_template: The `CliCallTemplate` for the tool.
+
         Returns:
-            The output from the command execution based on exit code:
-            - If exit code is 0: stdout (parsed as JSON if possible, otherwise raw string)
-            - If exit code is not 0: stderr
-            
+            The result of the command execution. If the command exits with a code
+            of 0, it returns the content of stdout. If the exit code is non-zero,
+            it returns the content of stderr. The output is parsed as JSON if
+            possible; otherwise, it is returned as a raw string.
+
         Raises:
-            ValueError: If provider is not a CliProvider or command_name is not set
+            ValueError: If `tool_call_template` is not an instance of
+                `CliCallTemplate` or if `command_name` is not set.
         """
         if not isinstance(tool_call_template, CliCallTemplate):
             raise ValueError("CliCommunicationProtocol can only be used with CliCallTemplate")
@@ -471,12 +489,10 @@ class CliCommunicationProtocol(CommunicationProtocol):
             raise
 
     async def call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: CallTemplate) -> AsyncGenerator[Any, None]:
-        """Streaming calls are not supported for CLI protocol."""
-        raise NotImplementedError("Streaming is not supported by the CLI communication protocol.")
-    
-    async def close(self) -> None:
-        """Close the transport.
-        
-        This is a no-op for CLI transports since they don't maintain connections.
+        """REQUIRED
+        Streaming calls are not supported for the CLI protocol.
+
+        Raises:
+            NotImplementedError: Always, as this functionality is not supported.
         """
-        self._log_info("Closing CLI transport (no-op)")
+        raise NotImplementedError("Streaming is not supported by the CLI communication protocol.")

utcp_cli-1.0.2/src/utcp_cli.egg-info/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: utcp-cli
+Version: 1.0.2
+Summary: UTCP communication protocol plugin for wrapping local command-line tools.
+Author: UTCP Contributors
+License-Expression: MPL-2.0
+Project-URL: Homepage, https://utcp.io
+Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
+Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: utcp>=1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# UTCP CLI Plugin
+
+[![PyPI Downloads](https://static.pepy.tech/badge/utcp-cli)](https://pepy.tech/projects/utcp-cli)
+
+Command-line interface plugin for UTCP, enabling integration with command-line tools and processes.
+
+## Features
+
+- **Command Execution**: Run any command-line tool as a UTCP tool
+- **Environment Variables**: Secure credential and configuration passing
+- **Working Directory Control**: Execute commands in specific directories
+- **Input/Output Handling**: Support for stdin, stdout, stderr processing
+- **Cross-Platform**: Works on Windows, macOS, and Linux
+- **Timeout Management**: Configurable execution timeouts
+- **Argument Validation**: Optional input sanitization
+
+## Installation
+
+```bash
+pip install utcp-cli
+```
+
+## Quick Start
+
+```python
+from utcp.utcp_client import UtcpClient
+
+# Basic CLI tool
+client = await UtcpClient.create(config={
+    "manual_call_templates": [{
+        "name": "file_tools",
+        "call_template_type": "cli",
+        "command_name": "ls -la ${path}"
+    }]
+})
+
+result = await client.call_tool("file_tools.list", {"path": "/home"})
+```
+
+## Configuration Examples
+
+### Basic Command
+```json
+{
+  "name": "file_ops",
+  "call_template_type": "cli",
+  "command_name": "ls -la ${path}",
+  "working_dir": "/tmp"
+}
+```
+
+### With Environment Variables
+```json
+{
+  "name": "python_script",
+  "call_template_type": "cli",
+  "command_name": "python script.py ${input}",
+  "env_vars": {
+    "PYTHONPATH": "/custom/path",
+    "API_KEY": "${API_KEY}"
+  }
+}
+```
+
+### Processing JSON with jq
+```json
+{
+  "name": "json_processor",
+  "call_template_type": "cli",
+  "command_name": "jq '.data'",
+  "stdin": "${json_input}",
+  "timeout": 10
+}
+```
+
+### Git Operations
+```json
+{
+  "name": "git_tools",
+  "call_template_type": "cli",
+  "command_name": "git ${operation} ${args}",
+  "working_dir": "${repo_path}",
+  "env_vars": {
+    "GIT_AUTHOR_NAME": "${author_name}",
+    "GIT_AUTHOR_EMAIL": "${author_email}"
+  }
+}
+```
+
+## Security Considerations
+
+- Commands run in isolated subprocesses
+- Environment variables provide secure credential passing
+- Working directory restrictions limit file system access
+- Input validation prevents command injection
+
+```json
+{
+  "name": "safe_grep",
+  "call_template_type": "cli",
+  "command_name": "grep ${pattern} ${file}",
+  "working_dir": "/safe/directory",
+  "allowed_args": {
+    "pattern": "^[a-zA-Z0-9_-]+$",
+    "file": "^[a-zA-Z0-9_./-]+\\.txt$"
+  }
+}
+```
+
+## Error Handling
+
+```python
+from utcp.exceptions import ToolCallError
+import subprocess
+
+try:
+    result = await client.call_tool("cli_tool.command", {"arg": "value"})
+except ToolCallError as e:
+    if isinstance(e.__cause__, subprocess.CalledProcessError):
+        print(f"Command failed with exit code {e.__cause__.returncode}")
+        print(f"stderr: {e.__cause__.stderr}")
+```
+
+## Common Use Cases
+
+- **File Operations**: ls, find, grep, awk, sed
+- **Data Processing**: jq, sort, uniq, cut
+- **System Monitoring**: ps, top, df, netstat
+- **Development Tools**: git, npm, pip, docker
+- **Custom Scripts**: Python, bash, PowerShell scripts
+
+## Testing CLI Tools
+
+```python
+import pytest
+from utcp.utcp_client import UtcpClient
+
+@pytest.mark.asyncio
+async def test_cli_tool():
+    client = await UtcpClient.create(config={
+        "manual_call_templates": [{
+            "name": "test_cli",
+            "call_template_type": "cli",
+            "command_name": "echo ${message}"
+        }]
+    })
+    
+    result = await client.call_tool("test_cli.echo", {"message": "hello"})
+    assert "hello" in result["stdout"]
+```
+
+## Related Documentation
+
+- [Main UTCP Documentation](../../../README.md)
+- [Core Package Documentation](../../../core/README.md)
+- [HTTP Plugin](../http/README.md)
+- [MCP Plugin](../mcp/README.md)
+- [Text Plugin](../text/README.md)
+
+## Examples
+
+For complete examples, see the [UTCP examples repository](https://github.com/universal-tool-calling-protocol/utcp-examples).

{utcp_cli-1.0.0 → utcp_cli-1.0.2}/src/utcp_cli.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+README.md
 pyproject.toml
 src/utcp_cli/__init__.py
 src/utcp_cli/cli_call_template.py

{utcp_cli-1.0.0 → utcp_cli-1.0.2}/tests/test_cli_communication_protocol.py

@@ -39,7 +39,7 @@ def main():
     if len(sys.argv) == 1:
         # Return UTCP manual
         tools_data = {
-            "version": "1.0.0",
+            "manual_version": "1.0.0",
             "name": "Mock CLI Tools",
             "description": "Mock CLI tools for testing",
             "tools": [

utcp_cli-1.0.0/PKG-INFO

@@ -1,25 +0,0 @@
-Metadata-Version: 2.4
-Name: utcp-cli
-Version: 1.0.0
-Summary: Universal Tool Calling Protocol (UTCP) client library for Python
-Author: UTCP Contributors
-License-Expression: MPL-2.0
-Project-URL: Homepage, https://utcp.io
-Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
-Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: utcp>=1.0
-Provides-Extra: dev
-Requires-Dist: build; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: twine; extra == "dev"

utcp_cli-1.0.0/src/utcp_cli/cli_call_template.py

@@ -1,44 +0,0 @@
-from typing import Optional, Dict, Literal
-from pydantic import Field
-
-from utcp.data.call_template import CallTemplate
-from utcp.interfaces.serializer import Serializer
-from utcp.exceptions import UtcpSerializerValidationError
-import traceback
-
-class CliCallTemplate(CallTemplate):
-    """Call template configuration for Command Line Interface tools.
-
-    Enables execution of command-line tools and programs as UTCP providers.
-    Supports environment variable injection and custom working directories.
-
-    Attributes:
-        call_template_type: Always "cli" for CLI providers.
-        command_name: The name or path of the command to execute.
-        env_vars: Optional environment variables to set during command execution.
-        working_dir: Optional custom working directory for command execution.
-        auth: Always None - CLI providers don't support authentication.
-    """
-
-    call_template_type: Literal["cli"] = "cli"
-    command_name: str
-    env_vars: Optional[Dict[str, str]] = Field(
-        default=None, description="Environment variables to set when executing the command"
-    )
-    working_dir: Optional[str] = Field(
-        default=None, description="Working directory for command execution"
-    )
-    auth: None = None
-
-
-class CliCallTemplateSerializer(Serializer[CliCallTemplate]):
-    """Serializer for CliCallTemplate."""
-
-    def to_dict(self, obj: CliCallTemplate) -> dict:
-        return obj.model_dump()
-
-    def validate_dict(self, obj: dict) -> CliCallTemplate:
-        try:
-            return CliCallTemplate.model_validate(obj)
-        except Exception as e:
-            raise UtcpSerializerValidationError("Invalid CliCallTemplate: " + traceback.format_exc()) from e

utcp_cli-1.0.0/src/utcp_cli.egg-info/PKG-INFO

@@ -1,25 +0,0 @@
-Metadata-Version: 2.4
-Name: utcp-cli
-Version: 1.0.0
-Summary: Universal Tool Calling Protocol (UTCP) client library for Python
-Author: UTCP Contributors
-License-Expression: MPL-2.0
-Project-URL: Homepage, https://utcp.io
-Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
-Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: utcp>=1.0
-Provides-Extra: dev
-Requires-Dist: build; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: coverage; extra == "dev"
-Requires-Dist: twine; extra == "dev"