### Quick Start: Multi-step CLI Tool with UtcpClient

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

Demonstrates a quick start example using the UtcpClient to execute a multi-step CLI tool. It defines a 'file_analysis' tool that changes directory and counts Python files, showcasing argument substitution.

```python
from utcp.utcp_client import UtcpClient

# Multi-step CLI tool
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "file_analysis",
        "call_template_type": "cli",
        "commands": [
            {
                "command": "cd UTCP_ARG_target_dir_UTCP_END",
                "append_to_final_output": false
            },
            {
                "command": "find . -type f -name '*.py' | wc -l"
            }
        ]
    }]
})

result = await client.call_tool("file_analysis.count_python_files", {"target_dir": "/project"})
```

--------------------------------

### Quick Start: Connect and Call MCP Tool via UTCP

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/mcp/README.md

Demonstrates how to initialize a UtcpClient to connect to an MCP server and subsequently call a tool provided by that server. It showcases the basic setup for integrating MCP tools within the UTCP framework.

```python
from utcp.utcp_client import UtcpClient

# Connect to MCP server
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "mcp_server",
        "call_template_type": "mcp",
        "config": {
            "mcpServers": {
                "filesystem": {
                    "command": "node",
                    "args": ["mcp-server.js"]
                }
            }
        }
    }]
})

# Call MCP tool through UTCP
result = await client.call_tool("mcp_server.filesystem.read_file", {
    "path": "/data/file.txt"
})
```

--------------------------------

### Configuration: Environment Variables and Output Control

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

An example demonstrating the use of environment variables and output control within a CLI tool configuration. It installs a Python package and then executes a script, using the output of the first command as input for the second.

```json
{
  "name": "python_pipeline",
  "call_template_type": "cli",
  "commands": [
    {
      "command": "python setup.py install",
      "append_to_final_output": false
    },
    {
      "command": "python script.py --input UTCP_ARG_input_file_UTCP_END --result \"$CMD_0_OUTPUT\"",
      "append_to_final_output": true
    }
  ],
  "env_vars": {
    "PYTHONPATH": "/custom/path",
    "API_KEY": "${API_KEY}"
  }
}
```

--------------------------------

### Cross-Platform Considerations: Windows PowerShell Commands

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

Provides examples of command syntax for Windows using PowerShell. This includes commands for getting child items and setting the current location.

```json
{
  "commands": [
    {"command": "Get-ChildItem UTCP_ARG_path_UTCP_END"},
    {"command": "Set-Location UTCP_ARG_dir_UTCP_END"}
  ]
}
```

--------------------------------

### Basic HTTP API Call with UtcpClient

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/http/README.md

Demonstrates how to initialize UtcpClient with a manual HTTP API call template and then invoke it. This example shows a GET request to retrieve user data, utilizing path parameters.

```python
from utcp.utcp_client import UtcpClient

# Basic HTTP API
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "api_service",
        "call_template_type": "http",
        "url": "https://api.example.com/users/{user_id}",
        "http_method": "GET"
    }]
})

result = await client.call_tool("api_service.get_user", {"user_id": "123"})
```

--------------------------------

### Install UTCP WebSocket Plugin (Bash)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/websocket/README.md

Installs the UTCP WebSocket plugin using pip. Supports both standard installation and development installation from a local path.

```bash
pip install utcp-websocket

# For development:
pip install -e plugins/communication_protocols/websocket
```

--------------------------------

### Install UTCP CLI Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

Installs the UTCP CLI plugin using pip. This is the primary method for getting the plugin into your Python environment.

```bash
pip install utcp-cli
```

--------------------------------

### Install utcp-mcp Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/mcp/README.md

Installs the utcp-mcp Python package using pip. This is the primary method for getting started with the plugin.

```bash
pip install utcp-mcp
```

--------------------------------

### Install Dependencies and Build UTCP Package

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/CLAUDE.md

Commands to set up a virtual environment, install project dependencies, build the UTCP package, and install it locally. Requires Python 3.10 and Conda.

```bash
# Create virtual environment and install dependencies
conda create --name utcp python=3.10
conda activate utcp
pip install -r requirements.txt
python -m pip install --upgrade pip

# Build the package
python -m build

# Install locally
pip install dist/utcp-<version>.tar.gz
```

--------------------------------

### Configuration: Cross-Platform Git Operations

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

A configuration example for performing Git operations across different platforms. It clones a repository, changes into it, and then logs recent commits and counts Python files.

```json
{
  "name": "git_analysis",
  "call_template_type": "cli",
  "commands": [
    {
      "command": "git clone UTCP_ARG_repo_url_UTCP_END temp_repo",
      "append_to_final_output": false
    },
    {
      "command": "cd temp_repo",
      "append_to_final_output": false  
    },
    {
      "command": "git log --oneline -10",
      "append_to_final_output": true
    },
    {
      "command": "echo \"Repository has $(find . -name '*.py' | wc -l) Python files\"",
      "append_to_final_output": true
    }
  ],
  "env_vars": {
    "GIT_AUTHOR_NAME": "UTCP Bot",
    "GIT_AUTHOR_EMAIL": "bot@utcp.dev"
  }
}
```

--------------------------------

### Cross-Platform Considerations: Unix/Linux/macOS Bash Commands

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

Provides examples of command syntax for Unix-like systems (Linux, macOS) using Bash. This includes commands for listing directory contents and changing directories.

```json
{
  "commands": [
    {"command": "ls -la UTCP_ARG_path_UTCP_END"},
    {"command": "cd UTCP_ARG_dir_UTCP_END"}
  ]
}
```

--------------------------------

### Install UTCP Core and HTTP Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Installs the core UTCP library along with the HTTP communication protocol plugin, which is commonly used for interacting with web-based tools. Additional plugins can be installed separately as needed.

```bash
pip install utcp utcp-http

pip install utcp-cli utcp-mcp utcp-text
```

--------------------------------

### Install utcp-http Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/http/README.md

Installs the utcp-http plugin using pip. This is the first step to enable HTTP communication capabilities within the UTCP framework.

```bash
pip install utcp-http
```

--------------------------------

### Install Additional UTCP Plugins

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/core/README.md

Installs optional UTCP plugins for command-line interface tools, Model Context Protocol, and file-based tools, enhancing UTCP's integration capabilities.

```bash
pip install utcp-cli utcp-mcp utcp-text
```

--------------------------------

### Configure Local MCP Server (Stdio Transport)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/mcp/README.md

Provides a JSON configuration example for connecting to a local MCP server using stdio transport. This setup is suitable for MCP servers running as child processes on the same machine.

```json
{
  "name": "local_mcp",
  "call_template_type": "mcp",
  "config": {
    "mcpServers": {
      "filesystem": {
        "command": "python",
        "args": ["-m", "mcp_filesystem_server"],
        "env": {"LOG_LEVEL": "INFO"}
      }
    }
  }
}
```

--------------------------------

### Install UTCP Python Packages

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Instructions for cloning the UTCP repository and installing core packages and specific protocol plugins in editable mode for development. This allows for direct modification of installed packages.

```bash
git clone https://github.com/universal-tool-calling-protocol/python-utcp.git
cd python-utcp

pip install -e "core[dev]"
pip install -e plugins/communication_protocols/http
```

--------------------------------

### Install UTCP GraphQL Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/gql/README.md

Installs the necessary library for the UTCP GraphQL communication protocol using pip.

```bash
pip install gql
```

--------------------------------

### Python: Build UTCP Packages

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Illustrates the steps to build distributable files for UTCP packages (core and plugins) using the standard Python build process. This involves setting up a virtual environment, installing the build tool, and running the build command within the package directory.

```shell
# 1. Create and activate a virtual environment.
# 2. Install build dependencies: pip install build
# 3. Navigate to the package directory (e.g., cd core).
# 4. Run the build: python -m build
# The distributable files (.whl and .tar.gz) will be in the dist/ directory.
```

--------------------------------

### Basic UTCP Client Usage in Python

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Demonstrates how to initialize a UTCP client with an HTTP API configuration and subsequently call a tool. This example shows the fundamental steps for interacting with tools using the UTCP Python library.

```python
from utcp.utcp_client import UtcpClient

# Create client with HTTP API
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "my_api",
        "call_template_type": "http",
        "url": "https://api.example.com/utcp"
    }]
})

# Call a tool
result = await client.call_tool("my_api.get_data", {"id": "123"})
```

--------------------------------

### Configuration: Basic Multi-Command Operation

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

A basic configuration example for multi-command operation. It defines a 'file_analysis' tool that changes to a specified directory and lists its contents, with an option to set the working directory.

```json
{
  "name": "file_analysis",
  "call_template_type": "cli",
  "commands": [
    {
      "command": "cd UTCP_ARG_target_dir_UTCP_END",
      "append_to_final_output": false
    },
    {
      "command": "ls -la"
    }
  ],
  "working_dir": "/tmp"
}
```

--------------------------------

### Python WebSocket Example: IoT Device Control (String Template)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/websocket/README.md

Demonstrates controlling an IoT device via WebSocket using a string template for the message. Placeholders are used for device ID, command, and value.

```python
{
    "name": "iot",
    "call_template_type": "websocket",
    "url": "wss://iot.example.com/devices",
    "message": "DEVICE:UTCP_ARG_device_id_UTCP_ARG CMD:UTCP_ARG_command_UTCP_ARG VAL:UTCP_ARG_value_UTCP_ARG"
}

# Sends: "DEVICE:light_01 CMD:SET_BRIGHTNESS VAL:75"
await client.call_tool("iot.control", {
    "device_id": "light_01",
    "command": "SET_BRIGHTNESS",
    "value": "75"
})
```

--------------------------------

### UTCP HTTP Plugin Configuration Examples

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/http/README.md

Provides various JSON configurations for the UTCP HTTP plugin, showcasing different functionalities. These include basic GET requests, POST requests with API key authentication, OAuth2 authentication, Server-Sent Events (SSE) for real-time data, and streaming HTTP for large data transfers.

```json
{
  "name": "my_api",
  "call_template_type": "http",
  "url": "https://api.example.com/data",
  "http_method": "GET"
}
```

```json
{
  "name": "secure_api",
  "call_template_type": "http",
  "url": "https://api.example.com/data",
  "http_method": "POST",
  "auth": {
    "auth_type": "api_key",
    "api_key": "${API_KEY}",
    "var_name": "X-API-Key",
    "location": "header"
  }
}
```

```json
{
  "name": "oauth_api",
  "call_template_type": "http",
  "url": "https://api.example.com/data",
  "auth": {
    "auth_type": "oauth2",
    "client_id": "${CLIENT_ID}",
    "client_secret": "${CLIENT_SECRET}",
    "token_url": "https://auth.example.com/token"
  }
}
```

```json
{
  "name": "event_stream",
  "call_template_type": "sse",
  "url": "https://api.example.com/events",
  "event_type": "message",
  "reconnect": true
}
```

```json
{
  "name": "large_data",
  "call_template_type": "streamable_http",
  "url": "https://api.example.com/download",
  "chunk_size": 8192
}
```

--------------------------------

### Install UTCP Core and HTTP Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/core/README.md

Installs the core UTCP library along with the HTTP communication protocol plugin, which is commonly used for interacting with RESTful APIs and SSE streams.

```bash
pip install utcp utcp-http
```

--------------------------------

### Install UTCP File Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/file/README.md

Installs the utcp-file package using pip. This is the primary method for adding the file plugin to your Python environment.

```bash
pip install utcp-file
```

--------------------------------

### Dict Message Template Example (JSON)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/websocket/README.md

Provides an example of a dictionary-based message template for structured JSON messages, utilizing UTCP argument placeholders for dynamic content.

```json
{
    "message": {
        "jsonrpc": "2.0",
        "method": "UTCP_ARG_method_UTCP_ARG",
        "params": "UTCP_ARG_params_UTCP_ARG",
        "id": 1
    }
}
```

--------------------------------

### String Message Template Example (HTTP - JSON)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/websocket/README.md

Demonstrates a string-based message template for constructing an HTTP request, using UTCP argument placeholders for dynamic host and resource information.

```json
{
    "message": "GET UTCP_ARG_resource_UTCP_ARG HTTP/1.1\r\nHost: UTCP_ARG_host_UTCP_ARG\r\n\r\n"
}
```

--------------------------------

### Python: Allowing Multiple Protocols

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Shows how to configure a manual to work with tools from multiple communication protocols by explicitly setting the `allowed_communication_protocols` list. This example allows both HTTP and CLI tools.

```python
from utcp_http.http_call_template import HttpCallTemplate

# This manual can register/call both HTTP and CLI tools
multi_protocol_manual = HttpCallTemplate(
    name="flexible_manual",
    call_template_type="http",
    url="https://api.example.com/utcp",
    allowed_communication_protocols=["http", "cli"]  # Explicitly allow both
)
```

--------------------------------

### GET /utcp

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

The discovery endpoint returns the tool manual, providing information about available tools and their capabilities.

```APIDOC
## GET /utcp

### Description
This endpoint serves as the discovery mechanism for the Universal Tool Calling Protocol (UTCP). It returns a JSON object containing the tool manual, which details the available tools, their descriptions, input/output schemas, and how to call them.

### Method
GET

### Endpoint
/utcp

### Parameters
(No parameters for this endpoint)

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **manual_version** (string) - The version of the UTCP manual.
- **utcp_version** (string) - The version of the UTCP protocol supported.
- **tools** (array) - An array of tool objects, each describing an available tool.
  - **name** (string) - The unique name of the tool.
  - **description** (string) - A human-readable description of what the tool does.
  - **tags** (array of strings) - Tags associated with the tool for categorization.
  - **inputs** (object) - The schema defining the expected input parameters for the tool.
  - **outputs** (object) - The schema defining the expected output of the tool.
  - **tool_call_template** (object) - Configuration for how to call the tool, specifying the protocol (e.g., HTTP), URL, and HTTP method.

#### Response Example
```json
{
  "manual_version": "1.0.0",
  "utcp_version": "1.0.2",
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "tags": ["weather"],
      "inputs": {
        "type": "object",
        "properties": {
          "location": {"type": "string"}
        }
      },
      "outputs": {
        "type": "object",
        "properties": {
          "temperature": {"type": "number"},
          "conditions": {"type": "string"}
        }
      },
      "tool_call_template": {
        "call_template_type": "http",
        "url": "https://example.com/api/weather",
        "http_method": "GET"
      }
    }
  ]
}
```
```

--------------------------------

### Create UTCP Client Instance with UtcpClient.create

Source: https://context7.com/universal-tool-calling-protocol/python-utcp/llms.txt

Demonstrates various ways to create a UTCP client instance using the `UtcpClient.create` factory method. This includes using default configurations, dictionary-based configurations, JSON files, and `UtcpClientConfig` objects. The client automatically handles plugin initialization and tool repository setup.

```python
import asyncio
from utcp.utcp_client import UtcpClient

async def main():
    # Option 1: Create with default configuration
    client = await UtcpClient.create()

    # Option 2: Create from dictionary configuration
    client = await UtcpClient.create(config={
        "variables": {
            "my__api_API_KEY": "your-api-key-here"
        },
        "load_variables_from": [
            {"variable_loader_type": "dotenv", "env_file_path": ".env"}
        ],
        "tool_repository": {"tool_repository_type": "in_memory"},
        "tool_search_strategy": {"tool_search_strategy_type": "tag_and_description_word_match"},
        "manual_call_templates": [
            {
                "name": "my_api",
                "call_template_type": "http",
                "url": "https://api.example.com/utcp",
                "http_method": "GET"
            }
        ]
    })

    # Option 3: Create from JSON config file
    client = await UtcpClient.create(config="./config.json")

    # Option 4: Create with UtcpClientConfig object
    from utcp.data.utcp_client_config import UtcpClientConfig
    from utcp_http.http_call_template import HttpCallTemplate

    config = UtcpClientConfig(
        variables={"my__api_BASE_URL": "https://api.example.com"},
        manual_call_templates=[
            HttpCallTemplate(
                name="my_api",
                url="$BASE_URL/tools",
                http_method="GET"
            )
        ]
    )
    client = await UtcpClient.create(config=config)

    return client

asyncio.run(main())
```

--------------------------------

### Configuration: Referencing Previous Command Output

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

An example demonstrating how to reference the output of a previous command within a CLI tool configuration. It checks the Git status and then echoes whether changes were detected.

```json
{
  "name": "conditional_processor",
  "call_template_type": "cli",
  "commands": [
    {
      "command": "git status --porcelain",
      "append_to_final_output": false
    },
    {
      "command": "echo \"Changes detected: $CMD_0_OUTPUT\"",
      "append_to_final_output": true
    }
  ]
}
```

--------------------------------

### Test MCP Integration with Pytest

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/mcp/README.md

A pytest example demonstrating how to test the integration of an MCP server with UTCP. It includes setting up a client, listing tools, and calling a tool with assertions to verify its functionality.

```python
@pytest.mark.asyncio
async def test_mcp_integration():
    client = await UtcpClient.create(config={
        "manual_call_templates": [{
            "name": "test_mcp",
            "call_template_type": "mcp",
            "config": {
                "mcpServers": {
                    "test": {
                        "command": "python",
                        "args": ["-m", "test_mcp_server"]
                    }
                }
            }
        }]
    })
    
    tools = await client.list_tools()
    assert len(tools) > 0
    
    result = await client.call_tool("test_mcp.echo", {"message": "test"})
    assert result["message"] == "test"
```

--------------------------------

### Python WebSocket Example: Stock Price API Call

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/websocket/README.md

Illustrates calling a stock price WebSocket API without a message template. It includes authentication details and an example of sending a subscription message.

```python
{
    "name": "stocks",
    "call_template_type": "websocket",
    "url": "wss://stream.example.com/stocks",
    "auth": {
        "auth_type": "api_key",
        "api_key": "${STOCK_API_KEY}",
        "var_name": "Authorization",
        "location": "header"
    }
}

# Sends: {"symbol": "AAPL", "action": "subscribe"}
await client.call_tool("stocks.subscribe", {
    "symbol": "AAPL",
    "action": "subscribe"
})
```

--------------------------------

### UTCP Client JSON Configuration File Example

Source: https://context7.com/universal-tool-calling-protocol/python-utcp/llms.txt

A comprehensive JSON configuration file for the UTCP client, detailing all available options. This includes variable definitions, multiple manual call templates (HTTP and CLI), tool repository settings, search strategies, and post-processing rules.

```json
{
  "variables": {
    "weather__api_BASE_URL": "https://api.weather.com",
    "weather__api_API_KEY": "weather-api-key",
    "github__api_TOKEN": "ghp_xxxx"
  },
  "load_variables_from": [
    {
      "variable_loader_type": "dotenv",
      "env_file_path": ".env"
    }
  ],
  "tool_repository": {
    "tool_repository_type": "in_memory"
  },
  "tool_search_strategy": {
    "tool_search_strategy_type": "tag_and_description_word_match"
  },
  "manual_call_templates": [
    {
      "name": "weather_api",
      "call_template_type": "http",
      "url": "$BASE_URL/forecast",
      "http_method": "GET",
      "auth": {
        "auth_type": "api_key",
        "api_key": "$API_KEY",
        "var_name": "X-Api-Key",
        "location": "header"
      },
      "allowed_communication_protocols": ["http"]
    },
    {
      "name": "github_api",
      "call_template_type": "http",
      "url": "https://api.github.com/openapi.json",
      "http_method": "GET",
      "auth_tools": {
        "auth_type": "api_key",
        "api_key": "Bearer $TOKEN",
        "var_name": "Authorization",
        "location": "header"
      }
    },
    {
      "name": "local_scripts",
      "call_template_type": "cli",
      "commands": [
        {"command": "python UTCP_ARG_script_UTCP_END", "append_to_final_output": true}
      ],
      "env_vars": {"PYTHONPATH": "/app"},
      "working_dir": "/scripts"
    }
  ],
  "post_processing": [
    {
      "tool_post_processor_type": "filter_dict",
      "only_include_keys": ["name", "result"],
      "only_include_tools": ["weather_api.get_forecast"]
    }
  ]
}

```

--------------------------------

### Configure GraphQL Client Manual

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/gql/README.md

Example JSON configuration for a GraphQL client manual within UTCP, specifying endpoint, operation type, headers, and header fields.

```json
{
  "name": "my_graph",
  "call_template_type": "graphql",
  "url": "https://your.graphql/endpoint",
  "operation_type": "query",
  "headers": { "x-client": "utcp" },
  "header_fields": ["x-session-id"]
}
```

--------------------------------

### Python WebSocket Example: JSON-RPC Call (Dict Template)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/websocket/README.md

Shows how to make a JSON-RPC call over WebSocket using a dictionary template for the message. It includes handling stringified parameters for non-string values.

```python
{
    "name": "jsonrpc",
    "call_template_type": "websocket",
    "url": "wss://rpc.example.com/ws",
    "message": {
        "jsonrpc": "2.0",
        "method": "UTCP_ARG_method_UTCP_ARG",
        "params": "UTCP_ARG_params_UTCP_ARG",
        "id": 1
    },
    "response_format": "json"
}

# Sends: {"jsonrpc": "2.0", "method": "getUser", "params": "{\"id\": 123}", "id": 1}
# Note: params is stringified since it's a non-string value in the template
result = await client.call_tool("jsonrpc.call", {
    "method": "getUser",
    "params": {"id": 123}
})
```

--------------------------------

### Call GraphQL Tool

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/gql/README.md

Example Python code demonstrating how to call a GraphQL tool using the UTCP client, including passing dynamic header fields.

```python
await client.call_tool("my_graph.someQuery", {"id": "123", "x-session-id": "abc"})
```

--------------------------------

### Configure Basic SSE Stream (Python)

Source: https://context7.com/universal-tool-calling-protocol/python-utcp/llms.txt

Shows a basic configuration for an SSE stream using `SseCallTemplate`. This example sets the stream name, type, URL, event type, and enables reconnection with a specified retry timeout.

```python
from utcp.call_templates.sse_call_template import SseCallTemplate

sse_basic = SseCallTemplate(
    name="live_updates",
    call_template_type="sse",
    url="https://api.example.com/events",
    event_type="message",
    reconnect=True,
    retry_timeout=30000
)
```

--------------------------------

### Python WebSocket Example: Chat Application (Dict Template)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/websocket/README.md

Defines a template for a chat application's WebSocket messages using a dictionary structure. It includes placeholders for channel, user, text, and a dynamic timestamp.

```python
{
    "name": "chat",
    "call_template_type": "websocket",
    "url": "wss://chat.example.com/ws",
    "message": {
        "type": "message",
        "channel": "UTCP_ARG_channel_UTCP_ARG",
        "user": "UTCP_ARG_user_UTCP_ARG",
        "text": "UTCP_ARG_text_UTCP_ARG",
        "timestamp": "{{now}}"
    }
}
```

--------------------------------

### Python: Convert OpenAPI to UTCP Tools

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Shows how to use the `OpenApiConverter` from `utcp_http` to transform an OpenAPI specification into UTCP tools. It includes an example of fetching an OpenAPI spec from a URL and demonstrates how to configure the `UtcpClient` to automatically detect and convert remote OpenAPI specs.

```python
from utcp_http.openapi_converter import OpenApiConverter
import aiohttp

# Convert any OpenAPI spec to UTCP tools
async def convert_api():
    async with aiohttp.ClientSession() as session:
        async with session.get("https://api.github.com/openapi.json") as response:
            openapi_spec = await response.json()
    
    converter = OpenApiConverter(openapi_spec)
    manual = converter.convert()
    
    print(f"Generated {len(manual.tools)} tools from GitHub API!")
    return manual

# Or use UTCP Client configuration for automatic detection
from utcp.utcp_client import UtcpClient

client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "github",
        "call_template_type": "http", 
        "url": "https://api.github.com/openapi.json",
        "auth_tools": {  # Authentication for generated tools requiring auth
            "auth_type": "api_key",
            "api_key": "Bearer ${GITHUB_TOKEN}",
            "var_name": "Authorization",
            "location": "header"
        }
    }]
})
```

--------------------------------

### Use UTCP File Plugin in Python

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/file/README.md

Demonstrates how to use the UtcpClient in Python to load a UTCP manual and call a tool that reads from a local file. It initializes the client, lists available tools, and prints the result of calling the 'get_mock_user' tool.

```python
import asyncio
from utcp.utcp_client import UtcpClient

async def main():
    # Create a client, providing the path to the manual.
    # The file plugin is used automatically for the "file" call_template_type.
    client = await UtcpClient.create(config={
        "manual_call_templates": [{
            "name": "local_file_tools",
            "call_template_type": "file",
            "file_path": "./manuals/local_tools.json"
        }]
    })

    # List the tools to confirm it was loaded
    tools = await client.list_tools()
    print("Available tools:", [tool.name for tool in tools])

    # Call the tool. The result will be the content of './mock_data/user.json'
    result = await client.call_tool("local_file_tools.get_mock_user", {{}})
    
    print("\nTool Result:")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Initialize UTCP Client in Python

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Demonstrates three ways to initialize the `UtcpClient` in Python: from a configuration file path, from a dictionary, or from a `UtcpClientConfig` object. It also shows how to call a tool and print the result.

```python
import asyncio
from utcp.utcp_client import UtcpClient
from utcp.data.utcp_client_config import UtcpClientConfig
from utcp_http.http_call_template import HttpCallTemplate
from utcp.data.variable_loader import VariableLoaderSerializer
from utcp.interfaces.tool_post_processor import ToolPostProcessorConfigSerializer

async def main():
    # Option 1: Initialize from a config file path
    # client_from_file = await UtcpClient.create(config="./config.json")

    # Option 2: Initialize from a dictionary
    client_from_dict = await UtcpClient.create(config={
        "variables": {
            "openlibrary_URL": "https://openlibrary.org/static/openapi.json"
        },
        "load_variables_from": [
            {
                "variable_loader_type": "dotenv",
                "env_file_path": ".env"
            }
        ],
        "tool_repository": {
            "tool_repository_type": "in_memory"
        },
        "tool_search_strategy": {
            "tool_search_strategy_type": "tag_and_description_word_match"
        },
        "manual_call_templates": [
            {
                "name": "openlibrary",
                "call_template_type": "http",
                "http_method": "GET",
                "url": "${URL}",
                "content_type": "application/json"
            }
        ],
        "post_processing": [
            {
                "tool_post_processor_type": "filter_dict",
                "only_include_keys": ["name", "key"],
                "only_include_tools": ["openlibrary.read_search_authors_json_search_authors_json_get"]
            }
        ]
    })

    # Option 3: Initialize with a full-featured UtcpClientConfig object
    config_obj = UtcpClientConfig(
        variables={"openlibrary_URL": "https://openlibrary.org/static/openapi.json"},
        load_variables_from=[
            VariableLoaderSerializer().validate_dict({
                "variable_loader_type": "dotenv", "env_file_path": ".env"
            })
        ],
        manual_call_templates=[
            HttpCallTemplate(
                name="openlibrary",
                call_template_type="http",
                http_method="GET",
                url="${URL}",
                content_type="application/json"
            )
        ],
        post_processing=[
            ToolPostProcessorConfigSerializer().validate_dict({
                "tool_post_processor_type": "filter_dict",
                "only_include_keys": ["name", "key"],
                "only_include_tools": ["openlibrary.read_search_authors_json_search_authors_json_get"]
            })
        ]
    )
    client = await UtcpClient.create(config=config_obj)

    # Call a tool. The name is namespaced: `manual_name.tool_name`
    result = await client.call_tool(
        tool_name="openlibrary.read_search_authors_json_search_authors_json_get",
        tool_args={"q": "J. K. Rowling"}
    )

    print(result)

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Initialize UTCP Client in Python

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/core/README.md

Demonstrates three ways to initialize the `UtcpClient` in Python: from a configuration file path, from a dictionary, or from a `UtcpClientConfig` object. It also shows how to call a tool and print the result.

```python
import asyncio
from utcp.utcp_client import UtcpClient
from utcp.data.utcp_client_config import UtcpClientConfig

async def main():
    # The UtcpClient can be created with a config file path, a dict, or a UtcpClientConfig object.

    # Option 1: Initialize from a config file path
    # client_from_file = await UtcpClient.create(config="./config.json")

    # Option 2: Initialize from a dictionary
    client_from_dict = await UtcpClient.create(config={
        "variables": {
            "openlibrary_URL": "https://openlibrary.org/static/openapi.json"
        },
        "load_variables_from": [
            {
                "variable_loader_type": "dotenv",
                "env_file_path": ".env"
            }
        ],
        "tool_repository": {
            "tool_repository_type": "in_memory"
        },
        "tool_search_strategy": {
            "tool_search_strategy_type": "tag_and_description_word_match"
        },
        "manual_call_templates": [
            {
                "name": "openlibrary",
                "call_template_type": "http",
                "http_method": "GET",
                "url": "${URL}",
                "content_type": "application/json"
            }
        ],
        "post_processing": [
            {
                "tool_post_processor_type": "filter_dict",
                "only_include_keys": ["name", "key"],
                "only_include_tools": ["openlibrary.read_search_authors_json_search_authors_json_get"]
            }
        ]
    })

    # Option 3: Initialize with a full-featured UtcpClientConfig object
    from utcp_http.http_call_template import HttpCallTemplate
    from utcp.data.variable_loader import VariableLoaderSerializer
    from utcp.interfaces.tool_post_processor import ToolPostProcessorConfigSerializer

    config_obj = UtcpClientConfig(
        variables={"openlibrary_URL": "https://openlibrary.org/static/openapi.json"},
        load_variables_from=[
            VariableLoaderSerializer().validate_dict({
                "variable_loader_type": "dotenv", "env_file_path": ".env"
            })
        ],
        manual_call_templates=[
            HttpCallTemplate(
                name="openlibrary",
                call_template_type="http",
                http_method="GET",
                url="${URL}",
                content_type="application/json"
            )
        ],
        post_processing=[
            ToolPostProcessorConfigSerializer().validate_dict({
                "tool_post_processor_type": "filter_dict",
                "only_include_keys": ["name", "key"],
                "only_include_tools": ["openlibrary.read_search_authors_json_search_authors_json_get"]
            })
        ]
    )
    client = await UtcpClient.create(config=config_obj)

    # Call a tool. The name is namespaced: `manual_name.tool_name`
    result = await client.call_tool(
        tool_name="openlibrary.read_search_authors_json_search_authors_json_get",
        tool_args={"q": "J. K. Rowling"}
    )

    print(result)

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Initialize UTCP Client with Configuration

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/CLAUDE.md

Python code snippet demonstrating how to initialize the UTCP client. It shows loading provider configurations from a JSON file and environment variables from a .env file.

```python
client = await UtcpClient.create(
    config={
        "providers_file_path": "./providers.json",
        "load_variables_from": [{"type": "dotenv", "env_file_path": ".env"}]
    }
)
```

--------------------------------

### Install utcp-text Plugin

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/text/README.md

Installs the 'utcp-text' Python package using pip. This package provides the text content plugin for UTCP.

```bash
pip install utcp-text
```

--------------------------------

### Install UTCP Socket Plugin and Core (Python)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/socket/README.md

Installs the core UTCP package with development extras and the socket communication protocol plugin in editable mode. Requires Python 3.10+ and pip.

```bash
pip install -e "./core[dev]"
pip install -e ./plugins/communication_protocols/socket[dev]
```

--------------------------------

### Discover Available Tools from MCP Server

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/mcp/README.md

Demonstrates how to list all available tools exposed by a connected MCP server using the `list_tools` method of the UtcpClient. The output shows the names of the discovered tools.

```python
# Discover tools from MCP server
tools = await client.list_tools()
print(f"Available tools: {[tool.name for tool in tools]}")
```

--------------------------------

### GET /api/weather

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Retrieves the current weather conditions for a specified location.

```APIDOC
## GET /api/weather

### Description
Retrieves the current weather conditions for a specified location.

### Method
GET

### Endpoint
/api/weather

### Parameters
#### Query Parameters
- **location** (string) - Required - The location for which to retrieve weather information.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **temperature** (number) - The current temperature in Celsius.
- **conditions** (string) - A description of the current weather conditions (e.g., "Sunny", "Cloudy").

#### Response Example
```json
{
  "temperature": 22.5,
  "conditions": "Sunny"
}
```
```

--------------------------------

### Run UTCP Socket Plugin Tests (Python)

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/socket/README.md

Executes all tests for the UTCP socket plugin using pytest. This command assumes the plugin and its dependencies are installed.

```bash
python -m pytest plugins/communication_protocols/socket/tests -v
```

--------------------------------

### Cross-Platform Considerations: Universal Commands

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/plugins/communication_protocols/cli/README.md

Lists commands that are generally compatible across different operating systems, such as Git status, Python version, and Node.js version checks.

```json
{
  "commands": [
    {"command": "git status"},
    {"command": "python --version"},
    {"command": "node -v"}
  ]
}
```

--------------------------------

### Define UTCP Manual with FastAPI

Source: https://github.com/universal-tool-calling-protocol/python-utcp/blob/main/README.md

Illustrates how to provide a UTCP manual for discovered tools using FastAPI. It shows the creation of a `UTCPManual` object and exposes it via a `/utcp` discovery endpoint, replacing `tool_provider` with `tool_call_template`.

```python
from fastapi import FastAPI
from utcp_http.http_call_template import HttpCallTemplate
from utcp.data.utcp_manual import UtcpManual
from utcp.python_specific_tooling.tool_decorator import utcp_tool

app = FastAPI()

# The discovery endpoint returns the tool manual
@app.get("/utcp")
def utcp_discovery():
    return UtcpManual.create_from_decorators(manual_version="1.0.0")

```