diff --git a/docs/llms.txt b/docs/llms.txt
new file mode 100644
index 0000000..b883b66
--- /dev/null
+++ b/docs/llms.txt
@@ -0,0 +1,9704 @@
+================================================================================
+UTCP SPECIFICATION - COMPLETE DOCUMENTATION
+================================================================================
+
+This file combines all markdown documentation from the UTCP specification.
+Generated from 55 markdown files.
+
+Table of Contents:
+--------------------------------------------------------------------------------
+ - api/core/utcp/data/auth.md
+ - api/core/utcp/data/auth_implementations/api_key_auth.md
+ - api/core/utcp/data/auth_implementations/basic_auth.md
+ - api/core/utcp/data/auth_implementations/oauth2_auth.md
+ - api/core/utcp/data/call_template.md
+ - api/core/utcp/data/register_manual_response.md
+ - api/core/utcp/data/tool.md
+ - api/core/utcp/data/utcp_client_config.md
+ - api/core/utcp/data/utcp_manual.md
+ - api/core/utcp/data/variable_loader.md
+ - api/core/utcp/data/variable_loader_implementations/dot_env_variable_loader.md
+ - api/core/utcp/exceptions/utcp_serializer_validation_error.md
+ - api/core/utcp/exceptions/utcp_variable_not_found_exception.md
+ - api/core/utcp/implementations/default_variable_substitutor.md
+ - api/core/utcp/implementations/in_mem_tool_repository.md
+ - api/core/utcp/implementations/post_processors/filter_dict_post_processor.md
+ - api/core/utcp/implementations/post_processors/limit_strings_post_processor.md
+ - api/core/utcp/implementations/tag_search.md
+ - api/core/utcp/implementations/utcp_client_implementation.md
+ - api/core/utcp/interfaces/communication_protocol.md
+ - api/core/utcp/interfaces/concurrent_tool_repository.md
+ - api/core/utcp/interfaces/serializer.md
+ - api/core/utcp/interfaces/tool_post_processor.md
+ - api/core/utcp/interfaces/tool_search_strategy.md
+ - api/core/utcp/interfaces/variable_substitutor.md
+ - api/core/utcp/plugins/discovery.md
+ - api/core/utcp/plugins/plugin_loader.md
+ - api/core/utcp/utcp_client.md
+ - api/index.md
+ - api/plugins/communication_protocols/cli/src/utcp_cli/cli_call_template.md
+ - api/plugins/communication_protocols/cli/src/utcp_cli/cli_communication_protocol.md
+ - api/plugins/communication_protocols/http/src/utcp_http/http_call_template.md
+ - api/plugins/communication_protocols/http/src/utcp_http/http_communication_protocol.md
+ - api/plugins/communication_protocols/http/src/utcp_http/openapi_converter.md
+ - api/plugins/communication_protocols/http/src/utcp_http/sse_call_template.md
+ - api/plugins/communication_protocols/http/src/utcp_http/sse_communication_protocol.md
+ - api/plugins/communication_protocols/http/src/utcp_http/streamable_http_call_template.md
+ - api/plugins/communication_protocols/http/src/utcp_http/streamable_http_communication_protocol.md
+ - api/plugins/communication_protocols/mcp/src/utcp_mcp/mcp_call_template.md
+ - api/plugins/communication_protocols/mcp/src/utcp_mcp/mcp_communication_protocol.md
+ - api/plugins/communication_protocols/text/src/utcp_text/text_call_template.md
+ - api/plugins/communication_protocols/text/src/utcp_text/text_communication_protocol.md
+ - for-tool-providers.md
+ - implementation.md
+ - index.md
+ - migration-v0.1-to-v1.0.md
+ - protocols/cli.md
+ - protocols/http.md
+ - protocols/index.md
+ - protocols/mcp.md
+ - protocols/sse.md
+ - protocols/streamable-http.md
+ - protocols/text.md
+ - security.md
+ - utcp-vs-mcp.md
+--------------------------------------------------------------------------------
+
+
+================================================================================
+FILE: api/core/utcp/data/auth.md
+================================================================================
+
+---
+title: auth
+sidebar_label: auth
+---
+
+# auth
+
+**File:** `core/src/utcp/data/auth.py`
+
+### class Auth {#auth}
+
+
+Documentation
+
+Authentication details for a provider.
+
+
+**Attributes**
+
+- **`auth_type`**: The authentication type identifier.
+
+
+#### Fields:
+
+- auth_type: str
+
+---
+
+### class AuthSerializer ([Serializer](./../interfaces/serializer.md#serializer)[Auth]) {#authserializer}
+
+
+Documentation
+
+[Serializer](./../interfaces/serializer.md#serializer) for authentication details.
+
+Defines the contract for serializers that convert authentication details to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting authentication details to dictionaries for storage or transmission
+- Converting dictionaries back to authentication details
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Fields:
+
+- auth_serializers: dict[str, [Serializer](./../interfaces/serializer.md#serializer)[Auth]]
+
+#### Methods:
+
+
+to_dict(self, obj: Auth) -> dict
+
+Convert an Auth object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The Auth object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the Auth object.
+
+
+
+validate_dict(self, obj: dict) -> Auth
+
+Validate a dictionary and convert it to an Auth object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The Auth object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/auth_implementations/api_key_auth.md
+================================================================================
+
+---
+title: api_key_auth
+sidebar_label: api_key_auth
+---
+
+# api_key_auth
+
+**File:** `core/src/utcp/data/auth_implementations/api_key_auth.py`
+
+### class ApiKeyAuth ([Auth](./../auth.md#auth)) {#apikeyauth}
+
+
+Documentation
+
+Authentication using an API key.
+
+The key can be provided directly or sourced from an environment variable.
+Supports placement in headers, query parameters, or cookies.
+
+
+**Attributes**
+
+- **`auth_type`**: The authentication type identifier, always "api_key".
+- **`api_key`**: The API key for authentication. Values starting with '$' or formatted as '$\{\}' are
+ treated as an injected variable from environment or configuration.
+- **`var_name`**: The name of the header, query parameter, or cookie that
+ contains the API key.
+- **`location`**: Where to include the API key (header, query parameter, or cookie).
+
+
+#### Fields:
+
+- auth_type: Literal['api_key']
+- api_key: str
+- var_name: str
+- location: Literal['header', 'query', 'cookie']
+
+---
+
+### class ApiKeyAuthSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[ApiKeyAuth]) {#apikeyauthserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: ApiKeyAuth) -> dict
+
+Convert an ApiKeyAuth object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The ApiKeyAuth object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the ApiKeyAuth object.
+
+
+
+validate_dict(self, obj: dict) -> ApiKeyAuth
+
+Validate a dictionary and convert it to an ApiKeyAuth object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The ApiKeyAuth object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/auth_implementations/basic_auth.md
+================================================================================
+
+---
+title: basic_auth
+sidebar_label: basic_auth
+---
+
+# basic_auth
+
+**File:** `core/src/utcp/data/auth_implementations/basic_auth.py`
+
+### class BasicAuth ([Auth](./../auth.md#auth)) {#basicauth}
+
+
+Documentation
+
+Authentication using HTTP Basic Authentication.
+
+Uses the standard HTTP Basic Authentication scheme with username and password
+encoded in the Authorization header.
+
+
+**Attributes**
+
+- **`auth_type`**: The authentication type identifier, always "basic".
+- **`username`**: The username for basic authentication. Recommended to use injected variables.
+- **`password`**: The password for basic authentication. Recommended to use injected variables.
+
+
+#### Fields:
+
+- auth_type: Literal['basic']
+- username: str
+- password: str
+
+---
+
+### class BasicAuthSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[BasicAuth]) {#basicauthserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: BasicAuth) -> dict
+
+Convert a BasicAuth object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The BasicAuth object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the BasicAuth object.
+
+
+
+validate_dict(self, obj: dict) -> BasicAuth
+
+Validate a dictionary and convert it to a BasicAuth object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The BasicAuth object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/auth_implementations/oauth2_auth.md
+================================================================================
+
+---
+title: oauth2_auth
+sidebar_label: oauth2_auth
+---
+
+# oauth2_auth
+
+**File:** `core/src/utcp/data/auth_implementations/oauth2_auth.py`
+
+### class OAuth2Auth ([Auth](./../auth.md#auth)) {#oauth2auth}
+
+
+Documentation
+
+Authentication using OAuth2 client credentials flow.
+
+Implements the OAuth2 client credentials grant type for machine-to-machine
+authentication. The client automatically handles token acquisition and refresh.
+
+
+**Attributes**
+
+- **`auth_type`**: The authentication type identifier, always "oauth2".
+- **`token_url`**: The URL endpoint to fetch the OAuth2 access token from. Recommended to use injected variables.
+- **`client_id`**: The OAuth2 client identifier. Recommended to use injected variables.
+- **`client_secret`**: The OAuth2 client secret. Recommended to use injected variables.
+- **`scope`**: Optional scope parameter to limit the access token's permissions.
+
+
+#### Fields:
+
+- auth_type: Literal['oauth2']
+- token_url: str
+- client_id: str
+- client_secret: str
+- scope: Optional[str]
+
+---
+
+### class OAuth2AuthSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[OAuth2Auth]) {#oauth2authserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: OAuth2Auth) -> dict
+
+Convert an OAuth2Auth object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The OAuth2Auth object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the OAuth2Auth object.
+
+
+
+validate_dict(self, obj: dict) -> OAuth2Auth
+
+Validate a dictionary and convert it to an OAuth2Auth object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The OAuth2Auth object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/call_template.md
+================================================================================
+
+---
+title: call_template
+sidebar_label: call_template
+---
+
+# call_template
+
+**File:** `core/src/utcp/data/call_template.py`
+
+### class CallTemplate {#calltemplate}
+
+
+Documentation
+
+Base class for all UTCP tool providers.
+
+This is the abstract base class that all specific call template implementations
+inherit from. It provides the common fields that every provider must have.
+
+
+**Attributes**
+
+- **`name`**: Unique identifier for the provider. Defaults to a random UUID hex string.
+ Should be unique across all providers and recommended to be set to a human-readable name.
+ Can only contain letters, numbers and underscores. All special characters must be replaced with underscores.
+- **`call_template_type`**: The transport protocol type used by this provider.
+
+
+#### Fields:
+
+- name: str
+- call_template_type: str
+- auth: Optional[[Auth](./auth.md#auth)]
+
+---
+
+### class CallTemplateSerializer ([Serializer](./../interfaces/serializer.md#serializer)[CallTemplate]) {#calltemplateserializer}
+
+
+Documentation
+
+[Serializer](./../interfaces/serializer.md#serializer) for call templates.
+
+Defines the contract for serializers that convert call templates to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting call templates to dictionaries for storage or transmission
+- Converting dictionaries back to call templates
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Fields:
+
+- call_template_serializers: dict[str, [Serializer](./../interfaces/serializer.md#serializer)[CallTemplate]]
+
+#### Methods:
+
+
+to_dict(self, obj: CallTemplate) -> dict
+
+Convert a CallTemplate object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The CallTemplate object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the CallTemplate object.
+
+
+
+validate_dict(self, obj: dict) -> CallTemplate
+
+Validate a dictionary and convert it to a CallTemplate object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The CallTemplate object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/register_manual_response.md
+================================================================================
+
+---
+title: register_manual_response
+sidebar_label: register_manual_response
+---
+
+# register_manual_response
+
+**File:** `core/src/utcp/data/register_manual_response.py`
+
+### class RegisterManualResult {#registermanualresult}
+
+
+Documentation
+
+Result of a manual registration.
+
+
+**Attributes**
+
+- **`manual_call_template`**: The call template of the registered manual.
+- **`manual`**: The registered manual.
+- **`success`**: Whether the registration was successful.
+- **`errors`**: List of error messages if registration failed.
+
+
+#### Fields:
+
+- manual_call_template: [CallTemplate](./call_template.md#calltemplate)
+- manual: [UtcpManual](./utcp_manual.md#utcpmanual)
+- success: bool
+- errors: List[str]
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/tool.md
+================================================================================
+
+---
+title: tool
+sidebar_label: tool
+---
+
+# tool
+
+**File:** `core/src/utcp/data/tool.py`
+
+### class JsonSchema {#jsonschema}
+
+
+Documentation
+
+JSON Schema for tool inputs and outputs.
+
+
+**Attributes**
+
+- **`schema_`**: Optional schema identifier.
+- **`id_`**: Optional schema identifier.
+- **`title`**: Optional schema title.
+- **`description`**: Optional schema description.
+- **`type`**: Optional schema type.
+- **`properties`**: Optional schema properties.
+- **`items`**: Optional schema items.
+- **`required`**: Optional schema required fields.
+- **`enum`**: Optional schema enum values.
+- **`const`**: Optional schema constant value.
+- **`default`**: Optional schema default value.
+- **`format`**: Optional schema format.
+- **`additionalProperties`**: Optional schema additional properties.
+
+
+#### Fields:
+
+- schema_: Optional[str]
+- id_: Optional[str]
+- title: Optional[str]
+- description: Optional[str]
+- type: Optional[Union[str, List[str]]]
+- properties: Optional[Dict[str, 'JsonSchema']]
+- items: Optional[Union['JsonSchema', List['JsonSchema']]]
+- required: Optional[List[str]]
+- enum: Optional[List[JsonType]]
+- const: Optional[JsonType]
+- default: Optional[JsonType]
+- format: Optional[str]
+- additionalProperties: Optional[Union[bool, 'JsonSchema']]
+- pattern: Optional[str]
+- minimum: Optional[float]
+- maximum: Optional[float]
+- minLength: Optional[int]
+- maxLength: Optional[int]
+- `model_config`
+
+---
+
+### class JsonSchemaSerializer ([Serializer](./../interfaces/serializer.md#serializer)[JsonSchema]) {#jsonschemaserializer}
+
+
+Documentation
+
+[Serializer](./../interfaces/serializer.md#serializer) for JSON Schema.
+
+Defines the contract for serializers that convert JSON Schema to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting JSON Schema to dictionaries for storage or transmission
+- Converting dictionaries back to JSON Schema
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Methods:
+
+
+to_dict(self, obj: JsonSchema) -> dict
+
+Convert a JsonSchema object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The JsonSchema object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the JsonSchema object.
+
+
+
+validate_dict(self, obj: dict) -> JsonSchema
+
+Validate a dictionary and convert it to a JsonSchema object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The JsonSchema object converted from the dictionary.
+
+
+---
+
+### class Tool {#tool}
+
+
+Documentation
+
+Definition of a UTCP tool.
+
+Represents a callable tool with its metadata, input/output schemas,
+and provider configuration. Tools are the fundamental units of
+functionality in the UTCP ecosystem.
+
+
+**Attributes**
+
+- **`name`**: Unique identifier for the tool, typically in format "provider.tool_name".
+- **`description`**: Human-readable description of what the tool does.
+- **`inputs`**: JSON Schema defining the tool's input parameters.
+- **`outputs`**: JSON Schema defining the tool's return value structure.
+- **`tags`**: List of tags for categorization and search.
+- **`average_response_size`**: Optional hint about typical response size in bytes.
+- **`tool_call_template`**: [CallTemplate](./call_template.md#calltemplate) configuration for accessing this tool.
+
+
+#### Fields:
+
+- name: str
+- description: str
+- inputs: JsonSchema
+- outputs: JsonSchema
+- tags: List[str]
+- average_response_size: Optional[int]
+- tool_call_template: [CallTemplate](./call_template.md#calltemplate)
+
+---
+
+### class ToolSerializer ([Serializer](./../interfaces/serializer.md#serializer)[Tool]) {#toolserializer}
+
+
+Documentation
+
+[Serializer](./../interfaces/serializer.md#serializer) for tools.
+
+Defines the contract for serializers that convert tools to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting tools to dictionaries for storage or transmission
+- Converting dictionaries back to tools
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Methods:
+
+
+to_dict(self, obj: Tool) -> dict
+
+Convert a Tool object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The Tool object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the Tool object.
+
+
+
+validate_dict(self, obj: dict) -> Tool
+
+Validate a dictionary and convert it to a Tool object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The Tool object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/utcp_client_config.md
+================================================================================
+
+---
+title: utcp_client_config
+sidebar_label: utcp_client_config
+---
+
+# utcp_client_config
+
+**File:** `core/src/utcp/data/utcp_client_config.py`
+
+### class UtcpClientConfig {#utcpclientconfig}
+
+
+Documentation
+
+Configuration model for UTCP client setup.
+
+Provides comprehensive configuration options for UTCP clients including
+variable definitions, provider file locations, and variable loading
+mechanisms. Supports hierarchical variable resolution with multiple
+sources.
+
+
+**Variable Resolution Order**
+
+1. Direct variables dictionary
+2. Custom variable loaders (in order)
+3. Environment variables
+
+
+
+**Attributes**
+
+variables for substitution.
+variable loader configurations for loading variables from external
+sources like .env files or remote services.
+repository, which manages the storage and retrieval of tools.
+Defaults to an in-memory repository.
+search strategy, defining how tools are looked up. Defaults to a
+tag and description-based search.
+configurations to be applied after a tool call.
+call templates for registering tools that don't have a provider.
+
+
+
+**Example**
+
+```python
+ config = UtcpClientConfig(
+ variables={"MANUAL__NAME_API_KEY_NAME": "$REMAPPED_API_KEY"},
+ load_variables_from=[
+ VariableLoaderSerializer().validate_dict({"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"
+ },
+ post_processing=[],
+ manual_call_templates=[]
+ )
+```
+
+
+#### Fields:
+
+- variables: Optional[Dict[str, str]]
+- load_variables_from: Optional[List[[VariableLoader](./variable_loader.md#variableloader)]]
+- tool_repository: [ConcurrentToolRepository](./../interfaces/concurrent_tool_repository.md#concurrenttoolrepository)
+- tool_search_strategy: [ToolSearchStrategy](./../interfaces/tool_search_strategy.md#toolsearchstrategy)
+- post_processing: List[[ToolPostProcessor](./../interfaces/tool_post_processor.md#toolpostprocessor)]
+- manual_call_templates: List[[CallTemplate](./call_template.md#calltemplate)]
+
+---
+
+### class UtcpClientConfigSerializer ([Serializer](./../interfaces/serializer.md#serializer)[UtcpClientConfig]) {#utcpclientconfigserializer}
+
+
+Documentation
+
+[Serializer](./../interfaces/serializer.md#serializer) for UTCP client configurations.
+
+Defines the contract for serializers that convert UTCP client configurations to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting UTCP client configurations to dictionaries for storage or transmission
+- Converting dictionaries back to UTCP client configurations
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Methods:
+
+
+to_dict(self, obj: UtcpClientConfig) -> dict
+
+Convert a UtcpClientConfig object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The UtcpClientConfig object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the UtcpClientConfig object.
+
+
+
+validate_dict(self, data: dict) -> UtcpClientConfig
+
+Validate a dictionary and convert it to a UtcpClientConfig object.
+
+
+**Args**
+
+- **`data`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The UtcpClientConfig object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/utcp_manual.md
+================================================================================
+
+---
+title: utcp_manual
+sidebar_label: utcp_manual
+---
+
+# utcp_manual
+
+**File:** `core/src/utcp/data/utcp_manual.py`
+
+### class UtcpManual {#utcpmanual}
+
+
+Documentation
+
+Standard format for tool provider responses during discovery.
+
+Represents the complete set of tools available from a provider, along
+with version information for compatibility checking. This format is
+returned by tool providers when clients query for available tools
+(e.g., through the `/utcp` endpoint or similar discovery mechanisms).
+
+The manual serves as the authoritative source of truth for what tools
+a provider offers and how they should be invoked.
+
+
+**Attributes**
+
+- **`version`**: UTCP protocol version supported by the provider.
+ Defaults to the current library version.
+- **`tools`**: List of available tools with their complete configurations
+ including input/output schemas, descriptions, and metadata.
+
+
+
+**Example**
+
+```python
+ @utcp_tool
+
+
+**Def Tool1()**
+
+pass
+
+@utcp_tool
+
+
+**Def Tool2()**
+
+pass
+
+# Create a manual from registered tools
+manual = UtcpManual.create_from_decorators()
+
+# Manual with specific tools
+manual = UtcpManual.create_from_decorators(
+manual_version="1.0.0",
+exclude=["tool1"]
+)
+```
+
+
+#### Fields:
+
+- utcp_version: str
+- manual_version: str
+- tools: List[[Tool](./tool.md#tool)]
+
+---
+
+### class UtcpManualSerializer ([Serializer](./../interfaces/serializer.md#serializer)[UtcpManual]) {#utcpmanualserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: UtcpManual) -> dict
+
+Convert a UtcpManual object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The UtcpManual object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the UtcpManual object.
+
+
+
+validate_dict(self, data: dict) -> UtcpManual
+
+Validate a dictionary and convert it to a UtcpManual object.
+
+
+**Args**
+
+- **`data`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The UtcpManual object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/variable_loader.md
+================================================================================
+
+---
+title: variable_loader
+sidebar_label: variable_loader
+---
+
+# variable_loader
+
+**File:** `core/src/utcp/data/variable_loader.py`
+
+### class VariableLoader {#variableloader}
+
+
+Documentation
+
+Abstract base class for variable loading configurations.
+
+Defines the interface for variable loaders that can retrieve variable
+values from different sources such as files, databases, or external
+services. Implementations provide specific loading mechanisms while
+maintaining a consistent interface.
+
+
+**Attributes**
+
+- **`variable_loader_type`**: Type identifier for the variable loader.
+
+
+#### Fields:
+
+- variable_loader_type: str
+
+#### Methods:
+
+
+get(self, key: str) -> Optional[str]
+
+Retrieve a variable value by key.
+
+
+**Args**
+
+- **`key`**: Variable name to retrieve.
+
+
+
+**Returns**
+
+Variable value if found, None otherwise.
+
+
+---
+
+### class VariableLoaderSerializer ([Serializer](./../interfaces/serializer.md#serializer)[VariableLoader]) {#variableloaderserializer}
+
+*No class documentation available*
+
+#### Fields:
+
+- loader_serializers: Dict[str, Type[[Serializer](./../interfaces/serializer.md#serializer)[VariableLoader]]]
+
+#### Methods:
+
+
+to_dict(self, obj: VariableLoader) -> dict
+
+Convert a VariableLoader object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The VariableLoader object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the VariableLoader object.
+
+
+
+validate_dict(self, data: dict) -> VariableLoader
+
+Validate a dictionary and convert it to a VariableLoader object.
+
+
+**Args**
+
+- **`data`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The VariableLoader object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/data/variable_loader_implementations/dot_env_variable_loader.md
+================================================================================
+
+---
+title: dot_env_variable_loader
+sidebar_label: dot_env_variable_loader
+---
+
+# dot_env_variable_loader
+
+**File:** `core/src/utcp/data/variable_loader_implementations/dot_env_variable_loader.py`
+
+### class DotEnvVariableLoader ([VariableLoader](./../variable_loader.md#variableloader)) {#dotenvvariableloader}
+
+
+Documentation
+
+Environment file variable loader implementation.
+
+Loads variables from .env files using the dotenv format. This loader
+supports the standard key=value format with optional quoting and
+comment support provided by the python-dotenv library.
+
+
+**Attributes**
+
+- **`env_file_path`**: Path to the .env file to load variables from.
+
+
+
+**Example**
+
+```python
+ loader = DotEnvVariableLoader(env_file_path=".env")
+ api_key = loader.get("API_KEY")
+```
+
+
+#### Fields:
+
+- variable_loader_type: Literal['dotenv']
+- env_file_path: str
+
+#### Methods:
+
+
+get(self, key: str) -> Optional[str]
+
+Load a variable from the configured .env file.
+
+
+**Args**
+
+- **`key`**: Variable name to retrieve from the environment file.
+
+
+
+**Returns**
+
+Variable value if found in the file, None otherwise.
+
+
+---
+
+### class DotEnvVariableLoaderSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[DotEnvVariableLoader]) {#dotenvvariableloaderserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: DotEnvVariableLoader) -> dict
+
+Convert a DotEnvVariableLoader object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The DotEnvVariableLoader object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the DotEnvVariableLoader object.
+
+
+
+validate_dict(self, data: dict) -> DotEnvVariableLoader
+
+Validate a dictionary and convert it to a DotEnvVariableLoader object.
+
+
+**Args**
+
+- **`data`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The DotEnvVariableLoader object converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/exceptions/utcp_serializer_validation_error.md
+================================================================================
+
+---
+title: utcp_serializer_validation_error
+sidebar_label: utcp_serializer_validation_error
+---
+
+# utcp_serializer_validation_error
+
+**File:** `core/src/utcp/exceptions/utcp_serializer_validation_error.py`
+
+### class UtcpSerializerValidationError {#utcpserializervalidationerror}
+
+
+Documentation
+
+Exception raised when a serializer validation fails.
+
+Thrown by serializers when they cannot validate or convert data structures
+due to invalid format, missing required fields, or type mismatches.
+Contains the original validation error details for debugging.
+
+
+**Usage**
+
+Typically caught when loading configuration files or processing
+external data that doesn't conform to UTCP specifications.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/exceptions/utcp_variable_not_found_exception.md
+================================================================================
+
+---
+title: utcp_variable_not_found_exception
+sidebar_label: utcp_variable_not_found_exception
+---
+
+# utcp_variable_not_found_exception
+
+**File:** `core/src/utcp/exceptions/utcp_variable_not_found_exception.py`
+
+### class UtcpVariableNotFound {#utcpvariablenotfound}
+
+
+Documentation
+
+Exception raised when a required variable cannot be found.
+
+This exception is thrown during variable substitution when a referenced
+variable cannot be resolved through any of the configured variable sources.
+It provides information about which variable was missing to help with
+debugging configuration issues.
+
+
+**Attributes**
+
+- **`variable_name`**: The name of the variable that could not be found.
+
+
+#### Fields:
+
+- variable_name: str
+
+#### Methods:
+
+
+__init__(self, variable_name: str)
+
+Initialize the exception with the missing variable name.
+
+
+**Args**
+
+- **`variable_name`**: Name of the variable that could not be found.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/implementations/default_variable_substitutor.md
+================================================================================
+
+---
+title: default_variable_substitutor
+sidebar_label: default_variable_substitutor
+---
+
+# default_variable_substitutor
+
+**File:** `core/src/utcp/implementations/default_variable_substitutor.py`
+
+### class DefaultVariableSubstitutor ([VariableSubstitutor](./../interfaces/variable_substitutor.md#variablesubstitutor)) {#defaultvariablesubstitutor}
+
+
+Documentation
+
+Default implementation of variable substitution.
+
+Provides a hierarchical variable resolution system that searches for
+
+**Variables In The Following Order**
+
+1. Configuration variables (exact match)
+2. Custom variable loaders (in order)
+3. Environment variables
+
+
+
+**Features**
+
+- Provider-specific variable namespacing
+- Hierarchical variable resolution
+- Recursive substitution in nested data structures
+- Variable discovery for validation
+
+
+
+**Variable Namespacing**
+
+Provider-specific variables are prefixed with the provider name
+to avoid conflicts. For example, a variable 'api_key' for provider
+'web_scraper' becomes 'web__scraper_api_key' internally.
+
+
+#### Methods:
+
+
+substitute(self, obj: dict | list | str, config: [UtcpClientConfig](./../data/utcp_client_config.md#utcpclientconfig), variable_namespace: Optional[str]) -> Any
+
+Recursively substitute variables in nested data structures.
+
+Performs deep substitution on dictionaries, lists, and strings.
+Non-string types are returned unchanged. String values are scanned
+for variable references using $\{VAR\} and $VAR syntax.
+
+
+**Args**
+
+- **`obj`**: Object to perform substitution on. Can be any type.
+- **`config`**: UTCP client configuration containing variable sources.
+- **`variable_namespace`**: Optional variable namespace.
+
+
+
+**Returns**
+
+Object with all variable references replaced. Structure and
+non-string values are preserved.
+
+
+
+**Raises**
+
+- **`[UtcpVariableNotFound](./../exceptions/utcp_variable_not_found_exception.md#utcpvariablenotfound)`**: If any referenced variable cannot be resolved.
+- **`ValueError`**: If variable_namespace contains invalid characters.
+
+
+
+**Example**
+
+```python
+ substitutor = DefaultVariableSubstitutor()
+ result = substitutor.substitute(
+ {"url": "https://${HOST}/api", "port": 8080},
+ config,
+ "my_provider"
+ )
+ # Returns: {"url": "https://api.example.com/api", "port": 8080}
+```
+
+
+
+find_required_variables(self, obj: dict | list | str, variable_namespace: Optional[str]) -> List[str]
+
+Recursively discover all variable references in a data structure.
+
+Scans the object for variable references using $\{VAR\} and $VAR syntax,
+returning fully-qualified variable names with variable namespacing.
+Useful for validation and dependency analysis.
+
+
+**Args**
+
+- **`obj`**: Object to scan for variable references.
+- **`variable_namespace`**: Variable namespace used for variable namespacing.
+ Variable names are prefixed with this variable namespace.
+
+
+
+**Raises**
+
+- **`ValueError`**: If variable_namespace contains invalid characters.
+
+
+
+**Returns**
+
+List of fully-qualified variable names found in the object.
+
+
+
+**Example**
+
+```python
+ substitutor = DefaultVariableSubstitutor()
+ vars = substitutor.find_required_variables(
+ {"url": "https://${HOST}/api", "key": "$API_KEY"},
+ "web_api"
+ )
+ # Returns: ["web__api_HOST", "web__api_API_KEY"]
+```
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/implementations/in_mem_tool_repository.md
+================================================================================
+
+---
+title: in_mem_tool_repository
+sidebar_label: in_mem_tool_repository
+---
+
+# in_mem_tool_repository
+
+**File:** `core/src/utcp/implementations/in_mem_tool_repository.py`
+
+### class InMemToolRepository ([ConcurrentToolRepository](./../interfaces/concurrent_tool_repository.md#concurrenttoolrepository)) {#inmemtoolrepository}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async save_manual(self, manual_call_template: [CallTemplate](./../data/call_template.md#calltemplate), manual: [UtcpManual](./../data/utcp_manual.md#utcpmanual)) -> None
+
+Save a manual and its associated tools.
+
+
+**Args**
+
+- **`manual_call_template`**: The manual call template to save.
+- **`manual`**: The manual to save.
+
+
+
+async remove_manual(self, manual_name: str) -> bool
+
+Remove a manual and its associated tools.
+
+
+**Args**
+
+- **`manual_name`**: The name of the manual to remove.
+
+
+
+**Returns**
+
+True if the manual was removed, False otherwise.
+
+
+
+async remove_tool(self, tool_name: str) -> bool
+
+Remove a tool from the repository.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to remove.
+
+
+
+**Returns**
+
+True if the tool was removed, False otherwise.
+
+
+
+async get_tool(self, tool_name: str) -> Optional[[Tool](./../data/tool.md#tool)]
+
+Get a tool by name.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to get.
+
+
+
+**Returns**
+
+The tool if it exists, None otherwise.
+
+
+
+async get_tools(self) -> List[[Tool](./../data/tool.md#tool)]
+
+Get all tools in the repository.
+
+
+**Returns**
+
+A list of all tools in the repository.
+
+
+
+async get_tools_by_manual(self, manual_name: str) -> Optional[List[[Tool](./../data/tool.md#tool)]]
+
+Get all tools associated with a manual.
+
+
+**Args**
+
+- **`manual_name`**: The name of the manual to get tools for.
+
+
+
+**Returns**
+
+A list of tools associated with the manual, or None if the manual does not exist.
+
+
+
+async get_manual(self, manual_name: str) -> Optional[[UtcpManual](./../data/utcp_manual.md#utcpmanual)]
+
+Get a manual by name.
+
+
+**Args**
+
+- **`manual_name`**: The name of the manual to get.
+
+
+
+**Returns**
+
+The manual if it exists, None otherwise.
+
+
+
+async get_manuals(self) -> List[[UtcpManual](./../data/utcp_manual.md#utcpmanual)]
+
+Get all manuals in the repository.
+
+
+**Returns**
+
+A list of all manuals in the repository.
+
+
+
+async get_manual_call_template(self, manual_call_template_name: str) -> Optional[[CallTemplate](./../data/call_template.md#calltemplate)]
+
+Get a manual call template by name.
+
+
+**Args**
+
+- **`manual_call_template_name`**: The name of the manual call template to get.
+
+
+
+**Returns**
+
+The manual call template if it exists, None otherwise.
+
+
+
+async get_manual_call_templates(self) -> List[[CallTemplate](./../data/call_template.md#calltemplate)]
+
+Get all manual call templates in the repository.
+
+
+**Returns**
+
+A list of all manual call templates in the repository.
+
+
+---
+
+### class InMemToolRepositoryConfigSerializer ([Serializer](./../interfaces/serializer.md#serializer)[InMemToolRepository]) {#inmemtoolrepositoryconfigserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: InMemToolRepository) -> dict
+
+Convert an `InMemToolRepository` instance to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The `InMemToolRepository` instance to convert.
+
+
+
+**Returns**
+
+A dictionary representing the `InMemToolRepository` instance.
+
+
+
+validate_dict(self, data: dict) -> InMemToolRepository
+
+Convert a dictionary to an `InMemToolRepository` instance.
+
+
+**Args**
+
+- **`data`**: The dictionary to convert.
+
+
+
+**Returns**
+
+An `InMemToolRepository` instance representing the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/implementations/post_processors/filter_dict_post_processor.md
+================================================================================
+
+---
+title: filter_dict_post_processor
+sidebar_label: filter_dict_post_processor
+---
+
+# filter_dict_post_processor
+
+**File:** `core/src/utcp/implementations/post_processors/filter_dict_post_processor.py`
+
+### class FilterDictPostProcessor ([ToolPostProcessor](./../../interfaces/tool_post_processor.md#toolpostprocessor)) {#filterdictpostprocessor}
+
+
+Documentation
+
+Post-processor that filters dictionary keys from tool results.
+
+Provides flexible filtering capabilities to include or exclude specific keys
+from dictionary results, with support for nested dictionaries and lists.
+Can be configured to apply filtering only to specific tools or manuals.
+
+
+**Attributes**
+
+- **`tool_post_processor_type`**: Always "filter_dict" for this processor.
+- **`exclude_keys`**: List of keys to remove from dictionary results.
+- **`only_include_keys`**: List of keys to keep in dictionary results (all others removed).
+- **`exclude_tools`**: List of tool names to skip processing for.
+- **`only_include_tools`**: List of tool names to process (all others skipped).
+- **`exclude_manuals`**: List of manual names to skip processing for.
+- **`only_include_manuals`**: List of manual names to process (all others skipped).
+
+
+#### Fields:
+
+- tool_post_processor_type: Literal['filter_dict']
+- exclude_keys: Optional[List[str]]
+- only_include_keys: Optional[List[str]]
+- exclude_tools: Optional[List[str]]
+- only_include_tools: Optional[List[str]]
+- exclude_manuals: Optional[List[str]]
+- only_include_manuals: Optional[List[str]]
+
+---
+
+### class FilterDictPostProcessorConfigSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[FilterDictPostProcessor]) {#filterdictpostprocessorconfigserializer}
+
+*No class documentation available*
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/implementations/post_processors/limit_strings_post_processor.md
+================================================================================
+
+---
+title: limit_strings_post_processor
+sidebar_label: limit_strings_post_processor
+---
+
+# limit_strings_post_processor
+
+**File:** `core/src/utcp/implementations/post_processors/limit_strings_post_processor.py`
+
+### class LimitStringsPostProcessor ([ToolPostProcessor](./../../interfaces/tool_post_processor.md#toolpostprocessor)) {#limitstringspostprocessor}
+
+
+Documentation
+
+Post-processor that limits the length of string values in tool results.
+
+Truncates string values to a specified maximum length to prevent
+excessively large responses. Processes nested dictionaries and lists
+recursively. Can be configured to apply limiting only to specific
+tools or manuals.
+
+
+**Attributes**
+
+- **`tool_post_processor_type`**: Always "limit_strings" for this processor.
+- **`limit`**: Maximum length for string values (default: 10000 characters).
+- **`exclude_tools`**: List of tool names to skip processing for.
+- **`only_include_tools`**: List of tool names to process (all others skipped).
+- **`exclude_manuals`**: List of manual names to skip processing for.
+- **`only_include_manuals`**: List of manual names to process (all others skipped).
+
+
+#### Fields:
+
+- tool_post_processor_type: Literal['limit_strings']
+- limit: int
+- exclude_tools: Optional[List[str]]
+- only_include_tools: Optional[List[str]]
+- exclude_manuals: Optional[List[str]]
+- only_include_manuals: Optional[List[str]]
+
+---
+
+### class LimitStringsPostProcessorConfigSerializer ([Serializer](./../../interfaces/serializer.md#serializer)[LimitStringsPostProcessor]) {#limitstringspostprocessorconfigserializer}
+
+*No class documentation available*
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/implementations/tag_search.md
+================================================================================
+
+---
+title: tag_search
+sidebar_label: tag_search
+---
+
+# tag_search
+
+**File:** `core/src/utcp/implementations/tag_search.py`
+
+### class TagAndDescriptionWordMatchStrategy ([ToolSearchStrategy](./../interfaces/tool_search_strategy.md#toolsearchstrategy)) {#taganddescriptionwordmatchstrategy}
+
+
+Documentation
+
+Tag and description word match strategy.
+
+
+**Implements A Weighted Scoring System That Matches Tools Based On**
+
+1. Tag matches (higher weight)
+2. Description word matches (lower weight)
+
+The strategy normalizes queries to lowercase, extracts words using regex,
+and calculates relevance scores for each tool. Results are sorted by
+score in descending order.
+
+
+
+**Attributes**
+
+- **`tool_search_strategy_type`**: Always "tag_and_description_word_match".
+- **`description_weight`**: Weight multiplier for description word matches (default: 1.0).
+- **`tag_weight`**: Weight multiplier for tag matches (default: 3.0).
+
+
+
+**Scoring Algorithm**
+
+- Each matching tag contributes tag_weight points
+- Each matching description word contributes description_weight points
+- Tools with higher scores are ranked first
+- Tools with zero score are included in results (ranked last)
+
+
+#### Fields:
+
+- tool_search_strategy_type: Literal['tag_and_description_word_match']
+- description_weight: float
+- tag_weight: float
+
+#### Methods:
+
+
+async search_tools(self, tool_repository: [ConcurrentToolRepository](./../interfaces/concurrent_tool_repository.md#concurrenttoolrepository), query: str, limit: int, any_of_tags_required: Optional[List[str]]) -> List[[Tool](./../data/tool.md#tool)]
+
+Search for tools based on the given query.
+
+
+**Args**
+
+- **`tool_repository`**: The tool repository to search in.
+- **`query`**: The query to search for.
+- **`limit`**: The maximum number of results to return.
+- **`any_of_tags_required`**: A list of tags that must be present in the tool.
+
+
+
+**Returns**
+
+A list of tools that match the query.
+
+
+---
+
+### class TagAndDescriptionWordMatchStrategyConfigSerializer ([Serializer](./../interfaces/serializer.md#serializer)[TagAndDescriptionWordMatchStrategy]) {#taganddescriptionwordmatchstrategyconfigserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: TagAndDescriptionWordMatchStrategy) -> dict
+
+Convert a `TagAndDescriptionWordMatchStrategy` instance to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The `TagAndDescriptionWordMatchStrategy` instance to convert.
+
+
+
+**Returns**
+
+A dictionary representing the `TagAndDescriptionWordMatchStrategy` instance.
+
+
+
+validate_dict(self, data: dict) -> TagAndDescriptionWordMatchStrategy
+
+Convert a dictionary to a `TagAndDescriptionWordMatchStrategy` instance.
+
+
+**Args**
+
+- **`data`**: The dictionary to convert.
+
+
+
+**Returns**
+
+A `TagAndDescriptionWordMatchStrategy` instance representing the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/implementations/utcp_client_implementation.md
+================================================================================
+
+---
+title: utcp_client_implementation
+sidebar_label: utcp_client_implementation
+---
+
+# utcp_client_implementation
+
+**File:** `core/src/utcp/implementations/utcp_client_implementation.py`
+
+### class UtcpClientImplementation ([UtcpClient](./../utcp_client.md#utcpclient)) {#utcpclientimplementation}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async create(cls, root_dir: Optional[str], config: Optional[Union[str, Dict[str, Any], [UtcpClientConfig](./../data/utcp_client_config.md#utcpclientconfig)]]) -> '[UtcpClient](./../utcp_client.md#utcpclient)'
+
+Create a new `[UtcpClient](./../utcp_client.md#utcpclient)` instance.
+
+
+**Args**
+
+- **`root_dir`**: The root directory for the client.
+- **`config`**: The configuration for the client.
+
+
+
+**Returns**
+
+A new `[UtcpClient](./../utcp_client.md#utcpclient)` instance.
+
+
+
+async register_manual(self, manual_call_template: [CallTemplate](./../data/call_template.md#calltemplate)) -> [RegisterManualResult](./../data/register_manual_response.md#registermanualresult)
+
+Register a manual in the client.
+
+
+**Args**
+
+- **`manual_call_template`**: The `[CallTemplate](./../data/call_template.md#calltemplate)` instance representing the manual to register.
+
+
+
+**Returns**
+
+A `[RegisterManualResult](./../data/register_manual_response.md#registermanualresult)` instance representing the result of the registration.
+
+
+
+async register_manuals(self, manual_call_templates: List[[CallTemplate](./../data/call_template.md#calltemplate)]) -> List[[RegisterManualResult](./../data/register_manual_response.md#registermanualresult)]
+
+Register multiple manuals in the client.
+
+
+**Args**
+
+- **`manual_call_templates`**: A list of `[CallTemplate](./../data/call_template.md#calltemplate)` instances representing the manuals to register.
+
+
+
+**Returns**
+
+A list of `[RegisterManualResult](./../data/register_manual_response.md#registermanualresult)` instances representing the results of the registration.
+
+
+
+async deregister_manual(self, manual_name: str) -> bool
+
+Deregister a manual from the client.
+
+
+**Args**
+
+- **`manual_name`**: The name of the manual to deregister.
+
+
+
+**Returns**
+
+A boolean indicating whether the manual was successfully deregistered.
+
+
+
+async call_tool(self, tool_name: str, tool_args: Dict[str, Any]) -> Any
+
+Call a tool in the client.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to call.
+- **`tool_args`**: A dictionary of arguments to pass to the tool.
+
+
+
+**Returns**
+
+The result of the tool call.
+
+
+
+async call_tool_streaming(self, tool_name: str, tool_args: Dict[str, Any]) -> AsyncGenerator[Any, None]
+
+Call a tool in the client streamingly.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to call.
+- **`tool_args`**: A dictionary of arguments to pass to the tool.
+
+
+
+**Returns**
+
+An async generator yielding the result of the tool call.
+
+
+
+async search_tools(self, query: str, limit: int, any_of_tags_required: Optional[List[str]]) -> List[[Tool](./../data/tool.md#tool)]
+
+Search for tools based on the given query.
+
+
+**Args**
+
+- **`query`**: The query to search for.
+- **`limit`**: The maximum number of results to return.
+- **`any_of_tags_required`**: A list of tags that must be present in the tool.
+
+
+
+**Returns**
+
+A list of tools that match the query.
+
+
+
+async get_required_variables_for_manual_and_tools(self, manual_call_template: [CallTemplate](./../data/call_template.md#calltemplate)) -> List[str]
+
+Get the required variables for a manual and its tools.
+
+
+**Args**
+
+- **`manual_call_template`**: The `[CallTemplate](./../data/call_template.md#calltemplate)` instance representing the manual.
+
+
+
+**Returns**
+
+A list of required variables for the manual and its tools.
+
+
+
+async get_required_variables_for_registered_tool(self, tool_name: str) -> List[str]
+
+Get the required variables for a registered tool.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool.
+
+
+
+**Returns**
+
+A list of required variables for the tool.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/interfaces/communication_protocol.md
+================================================================================
+
+---
+title: communication_protocol
+sidebar_label: communication_protocol
+---
+
+# communication_protocol
+
+**File:** `core/src/utcp/interfaces/communication_protocol.py`
+
+### class CommunicationProtocol {#communicationprotocol}
+
+
+Documentation
+
+Abstract interface for UTCP client transport implementations.
+
+Defines the contract that all transport implementations must follow to
+integrate with the UTCP client. Each transport handles communication
+with a specific type of provider (HTTP, CLI, WebSocket, etc.).
+
+
+**Transport Implementations Are Responsible For**
+
+- Discovering available tools from providers
+- Managing provider lifecycle (registration/deregistration)
+- Executing tool calls through the appropriate protocol
+
+
+#### Fields:
+
+- communication_protocols: dict[str, 'CommunicationProtocol']
+
+#### Methods:
+
+
+async register_manual(self, caller: '[UtcpClient](./../utcp_client.md#utcpclient)', manual_call_template: [CallTemplate](./../data/call_template.md#calltemplate)) -> [RegisterManualResult](./../data/register_manual_response.md#registermanualresult)
+
+Register a manual and its tools.
+
+Connects to the provider and retrieves the list of tools it offers.
+This may involve making discovery requests, parsing configuration files,
+or initializing connections depending on the provider type.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`manual_call_template`**: The call template of the manual to register.
+
+
+
+**Returns**
+
+[RegisterManualResult](./../data/register_manual_response.md#registermanualresult) object containing the call template and manual.
+
+
+
+**Raises**
+
+- **`ConnectionError`**: If unable to connect to the provider.
+- **`ValueError`**: If the provider configuration is invalid.
+
+
+
+async deregister_manual(self, caller: '[UtcpClient](./../utcp_client.md#utcpclient)', manual_call_template: [CallTemplate](./../data/call_template.md#calltemplate)) -> None
+
+Deregister a manual and its tools.
+
+Cleanly disconnects from the provider and releases any associated
+resources such as connections, processes, or file handles.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`manual_call_template`**: The call template of the manual to deregister.
+
+
+
+**Note**
+
+Should handle cases where the provider is already disconnected
+or was never properly registered.
+
+
+
+async call_tool(self, caller: '[UtcpClient](./../utcp_client.md#utcpclient)', tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../data/call_template.md#calltemplate)) -> Any
+
+Execute a tool call through this transport.
+
+Sends a tool invocation request to the provider using the appropriate
+protocol and returns the result. Handles serialization of arguments
+and deserialization of responses according to the transport type.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`tool_name`**: Name of the tool to call (may include provider prefix).
+- **`tool_args`**: Dictionary of arguments to pass to the tool.
+- **`tool_call_template`**: Call template of the tool to call.
+
+
+
+**Returns**
+
+The tool's response, with type depending on the tool's output schema.
+
+
+
+**Raises**
+
+- **`ToolNotFoundError`**: If the specified tool doesn't exist.
+- **`ValidationError`**: If the arguments don't match the tool's input schema.
+- **`ConnectionError`**: If unable to communicate with the provider.
+- **`TimeoutError`**: If the tool call exceeds the configured timeout.
+
+
+
+async call_tool_streaming(self, caller: '[UtcpClient](./../utcp_client.md#utcpclient)', tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../data/call_template.md#calltemplate)) -> AsyncGenerator[Any, None]
+
+Execute a tool call through this transport streamingly.
+
+Sends a tool invocation request to the provider using the appropriate
+protocol and returns the result. Handles serialization of arguments
+and deserialization of responses according to the transport type.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`tool_name`**: Name of the tool to call (may include provider prefix).
+- **`tool_args`**: Dictionary of arguments to pass to the tool.
+- **`tool_call_template`**: Call template of the tool to call.
+
+
+
+**Returns**
+
+An async generator that yields the tool's response, with type depending on the tool's output schema.
+
+
+
+**Raises**
+
+- **`ToolNotFoundError`**: If the specified tool doesn't exist.
+- **`ValidationError`**: If the arguments don't match the tool's input schema.
+- **`ConnectionError`**: If unable to communicate with the provider.
+- **`TimeoutError`**: If the tool call exceeds the configured timeout.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/interfaces/concurrent_tool_repository.md
+================================================================================
+
+---
+title: concurrent_tool_repository
+sidebar_label: concurrent_tool_repository
+---
+
+# concurrent_tool_repository
+
+**File:** `core/src/utcp/interfaces/concurrent_tool_repository.py`
+
+### class ConcurrentToolRepository {#concurrenttoolrepository}
+
+
+Documentation
+
+Abstract interface for tool and provider storage implementations.
+
+Defines the contract for repositories that manage the lifecycle and storage
+
+**Of Utcp Tools And Call Templates. Repositories Are Responsible For**
+
+- Persisting provider configurations and their associated tools
+- Providing efficient lookup and retrieval operations
+- Managing relationships between call templates and tools
+- Ensuring data consistency during operations
+- Thread safety
+
+The repository interface supports both individual and bulk operations,
+allowing for flexible implementation strategies ranging from simple
+in-memory storage to sophisticated database backends.
+
+
+
+**Note**
+
+All methods are async to support both synchronous and asynchronous
+storage implementations.
+
+
+#### Fields:
+
+- tool_repository_type: str
+
+#### Methods:
+
+
+async save_manual(self, manual_call_template: [CallTemplate](./../data/call_template.md#calltemplate), manual: [UtcpManual](./../data/utcp_manual.md#utcpmanual)) -> None
+
+Save a manual and its tools in the repository.
+
+
+**Args**
+
+- **`manual_call_template`**: The call template associated with the manual to save.
+- **`manual`**: The manual to save.
+
+
+
+async remove_manual(self, manual_name: str) -> bool
+
+Remove a manual and its tools from the repository.
+
+
+**Args**
+
+- **`manual_name`**: The name of the manual to remove.
+
+
+
+**Returns**
+
+True if the manual was removed, False otherwise.
+
+
+
+async remove_tool(self, tool_name: str) -> bool
+
+Remove a tool from the repository.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to remove.
+
+
+
+**Returns**
+
+True if the tool was removed, False otherwise.
+
+
+
+async get_tool(self, tool_name: str) -> Optional[[Tool](./../data/tool.md#tool)]
+
+Get a tool from the repository.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to retrieve.
+
+
+
+**Returns**
+
+The tool if found, otherwise None.
+
+
+
+async get_tools(self) -> List[[Tool](./../data/tool.md#tool)]
+
+Get all tools from the repository.
+
+
+**Returns**
+
+A list of tools.
+
+
+
+async get_tools_by_manual(self, manual_name: str) -> Optional[List[[Tool](./../data/tool.md#tool)]]
+
+Get tools associated with a specific manual.
+
+
+**Args**
+
+- **`manual_name`**: The name of the manual.
+
+
+
+**Returns**
+
+A list of tools associated with the manual, or None if the manual is not found.
+
+
+
+async get_manual(self, manual_name: str) -> Optional[[UtcpManual](./../data/utcp_manual.md#utcpmanual)]
+
+Get a manual from the repository.
+
+
+**Args**
+
+- **`manual_name`**: The name of the manual to retrieve.
+
+
+
+**Returns**
+
+The manual if found, otherwise None.
+
+
+
+async get_manuals(self) -> List[[UtcpManual](./../data/utcp_manual.md#utcpmanual)]
+
+Get all manuals from the repository.
+
+
+**Returns**
+
+A list of manuals.
+
+
+
+async get_manual_call_template(self, manual_call_template_name: str) -> Optional[[CallTemplate](./../data/call_template.md#calltemplate)]
+
+Get a manual call template from the repository.
+
+
+**Args**
+
+- **`manual_call_template_name`**: The name of the manual call template to retrieve.
+
+
+
+**Returns**
+
+The manual call template if found, otherwise None.
+
+
+
+async get_manual_call_templates(self) -> List[[CallTemplate](./../data/call_template.md#calltemplate)]
+
+Get all manual call templates from the repository.
+
+
+**Returns**
+
+A list of manual call templates.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/interfaces/serializer.md
+================================================================================
+
+---
+title: serializer
+sidebar_label: serializer
+---
+
+# serializer
+
+**File:** `core/src/utcp/interfaces/serializer.py`
+
+### class Serializer (Generic[T]) {#serializer}
+
+
+Documentation
+
+Abstract interface for serializers.
+
+Defines the contract for serializers that convert objects to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting objects to dictionaries for storage or transmission
+- Converting dictionaries back to objects
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Methods:
+
+
+validate_dict(self, obj: dict) -> T
+
+Validate a dictionary and convert it to an object.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The object converted from the dictionary.
+
+
+
+to_dict(self, obj: T) -> dict
+
+Convert an object to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The object to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the object.
+
+
+
+copy(self, obj: T) -> T
+
+Create a copy of an object.
+
+
+**Args**
+
+- **`obj`**: The object to copy.
+
+
+
+**Returns**
+
+A copy of the object.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/interfaces/tool_post_processor.md
+================================================================================
+
+---
+title: tool_post_processor
+sidebar_label: tool_post_processor
+---
+
+# tool_post_processor
+
+**File:** `core/src/utcp/interfaces/tool_post_processor.py`
+
+### class ToolPostProcessor {#toolpostprocessor}
+
+
+Documentation
+
+Abstract interface for tool post processors.
+
+Defines the contract for tool post processors that process the result of a tool call.
+
+**[Tool](./../data/tool.md#tool) Post Processors Are Responsible For**
+
+- Processing the result of a tool call
+- Returning the processed result
+
+
+#### Fields:
+
+- tool_post_processor_type: str
+
+#### Methods:
+
+
+post_process(self, caller: '[UtcpClient](./../utcp_client.md#utcpclient)', tool: [Tool](./../data/tool.md#tool), manual_call_template: '[CallTemplate](./../data/call_template.md#calltemplate)', result: Any) -> Any
+
+Process the result of a tool call.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`tool`**: The tool that was called.
+- **`manual_call_template`**: The call template of the manual that was called.
+- **`result`**: The result of the tool call.
+
+
+
+**Returns**
+
+The processed result.
+
+
+---
+
+### class ToolPostProcessorConfigSerializer ([Serializer](./serializer.md#serializer)[ToolPostProcessor]) {#toolpostprocessorconfigserializer}
+
+
+Documentation
+
+[Serializer](./serializer.md#serializer) for tool post processors.
+
+Defines the contract for serializers that convert tool post processors to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting tool post processors to dictionaries for storage or transmission
+- Converting dictionaries back to tool post processors
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Fields:
+
+- tool_post_processor_implementations: Dict[str, [Serializer](./serializer.md#serializer)[ToolPostProcessor]]
+
+#### Methods:
+
+
+to_dict(self, obj: ToolPostProcessor) -> dict
+
+Convert a tool post processor to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The tool post processor to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the tool post processor.
+
+
+
+validate_dict(self, data: dict) -> ToolPostProcessor
+
+Validate a dictionary and convert it to a tool post processor.
+
+
+**Args**
+
+- **`data`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The tool post processor converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/interfaces/tool_search_strategy.md
+================================================================================
+
+---
+title: tool_search_strategy
+sidebar_label: tool_search_strategy
+---
+
+# tool_search_strategy
+
+**File:** `core/src/utcp/interfaces/tool_search_strategy.py`
+
+### class ToolSearchStrategy {#toolsearchstrategy}
+
+
+Documentation
+
+Abstract interface for tool search implementations.
+
+Defines the contract for tool search strategies that can be plugged into
+the UTCP client. Different implementations can provide various search
+algorithms such as tag-based matching, semantic similarity, or keyword
+search.
+
+
+**Search Strategies Are Responsible For**
+
+- Interpreting search queries
+- Ranking tools by relevance
+- Limiting results appropriately
+- Providing consistent search behavior
+
+
+#### Fields:
+
+- tool_search_strategy_type: str
+
+#### Methods:
+
+
+async search_tools(self, tool_repository: [ConcurrentToolRepository](./concurrent_tool_repository.md#concurrenttoolrepository), query: str, limit: int, any_of_tags_required: Optional[List[str]]) -> List[[Tool](./../data/tool.md#tool)]
+
+Search for tools relevant to the query.
+
+Executes a search against the available tools and returns the most
+relevant matches ranked by the strategy's scoring algorithm.
+
+
+**Args**
+
+- **`tool_repository`**: The tool repository to search within.
+- **`query`**: The search query string. Format depends on the strategy
+ (e.g., keywords, tags, natural language).
+- **`limit`**: Maximum number of tools to return. Use 0 for no limit.
+ Strategies should respect this limit for performance.
+- **`any_of_tags_required`**: Optional list of tags where one of them must be present in the tool's tags
+ for it to be considered a match.
+
+
+
+**Returns**
+
+List of [Tool](./../data/tool.md#tool) objects ranked by relevance, limited to the
+specified count. Empty list if no matches found.
+
+
+
+**Raises**
+
+- **`ValueError`**: If the query format is invalid for this strategy.
+- **`RuntimeError`**: If the search operation fails unexpectedly.
+
+
+---
+
+### class ToolSearchStrategyConfigSerializer ([Serializer](./serializer.md#serializer)[ToolSearchStrategy]) {#toolsearchstrategyconfigserializer}
+
+
+Documentation
+
+[Serializer](./serializer.md#serializer) for tool search strategies.
+
+Defines the contract for serializers that convert tool search strategies to and from
+
+**Dictionaries For Storage Or Transmission. Serializers Are Responsible For**
+
+- Converting tool search strategies to dictionaries for storage or transmission
+- Converting dictionaries back to tool search strategies
+- Ensuring data consistency during serialization and deserialization
+
+
+#### Fields:
+
+- tool_search_strategy_implementations: Dict[str, [Serializer](./serializer.md#serializer)['ToolSearchStrategy']]
+- `default_strategy`
+
+#### Methods:
+
+
+to_dict(self, obj: ToolSearchStrategy) -> dict
+
+Convert a tool search strategy to a dictionary.
+
+
+**Args**
+
+- **`obj`**: The tool search strategy to convert.
+
+
+
+**Returns**
+
+The dictionary converted from the tool search strategy.
+
+
+
+validate_dict(self, data: dict) -> ToolSearchStrategy
+
+Validate a dictionary and convert it to a tool search strategy.
+
+
+**Args**
+
+- **`data`**: The dictionary to validate and convert.
+
+
+
+**Returns**
+
+The tool search strategy converted from the dictionary.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/interfaces/variable_substitutor.md
+================================================================================
+
+---
+title: variable_substitutor
+sidebar_label: variable_substitutor
+---
+
+# variable_substitutor
+
+**File:** `core/src/utcp/interfaces/variable_substitutor.py`
+
+### class VariableSubstitutor {#variablesubstitutor}
+
+*No class documentation available*
+
+#### Methods:
+
+
+substitute(self, obj: dict | list | str, config: [UtcpClientConfig](./../data/utcp_client_config.md#utcpclientconfig), variable_namespace: Optional[str]) -> Any
+
+Substitute variables in the given object.
+
+
+**Args**
+
+- **`obj`**: Object containing potential variable references to substitute.
+- **`config`**: UTCP client configuration containing variable definitions
+ and loaders.
+- **`variable_namespace`**: Optional variable namespace.
+
+
+
+**Returns**
+
+Object with all variable references replaced by their values.
+
+
+
+**Raises**
+
+- **`[UtcpVariableNotFound](./../exceptions/utcp_variable_not_found_exception.md#utcpvariablenotfound)`**: If a referenced variable cannot be resolved.
+
+
+
+find_required_variables(self, obj: dict | list | str, variable_namespace: Optional[str]) -> List[str]
+
+Find all variable references in the given object.
+
+
+**Args**
+
+- **`obj`**: Object to scan for variable references.
+- **`variable_namespace`**: Optional variable namespace.
+
+
+
+**Returns**
+
+List of fully-qualified variable names found in the object.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/plugins/discovery.md
+================================================================================
+
+---
+title: discovery
+sidebar_label: discovery
+---
+
+# discovery
+
+**File:** `core/src/utcp/plugins/discovery.py`
+
+### Function register_auth(auth_type: str, serializer: [Serializer](./../interfaces/serializer.md#serializer)[[Auth](./../data/auth.md#auth)], override: bool) -> bool {#register_auth}
+
+
+Documentation
+
+Register an authentication implementation.
+
+
+**Args**
+
+- **`auth_type`**: The authentication type identifier.
+- **`serializer`**: The serializer for the authentication implementation.
+- **`override`**: Whether to override an existing implementation.
+
+
+
+**Returns**
+
+True if the implementation was registered, False otherwise.
+
+
+---
+
+### Function register_variable_loader(loader_type: str, serializer: [Serializer](./../interfaces/serializer.md#serializer)[[VariableLoader](./../data/variable_loader.md#variableloader)], override: bool) -> bool {#register_variable_loader}
+
+
+Documentation
+
+Register a variable loader implementation.
+
+
+**Args**
+
+- **`loader_type`**: The variable loader type identifier.
+- **`serializer`**: The serializer for the variable loader implementation.
+- **`override`**: Whether to override an existing implementation.
+
+
+
+**Returns**
+
+True if the implementation was registered, False otherwise.
+
+
+---
+
+### Function register_call_template(call_template_type: str, serializer: [Serializer](./../interfaces/serializer.md#serializer)[[CallTemplate](./../data/call_template.md#calltemplate)], override: bool) -> bool {#register_call_template}
+
+
+Documentation
+
+Register a call template implementation.
+
+
+**Args**
+
+- **`call_template_type`**: The call template type identifier.
+- **`serializer`**: The serializer for the call template implementation.
+- **`override`**: Whether to override an existing implementation.
+
+
+
+**Returns**
+
+True if the implementation was registered, False otherwise.
+
+
+---
+
+### Function register_communication_protocol(communication_protocol_type: str, communication_protocol: [CommunicationProtocol](./../interfaces/communication_protocol.md#communicationprotocol), override: bool) -> bool {#register_communication_protocol}
+
+
+Documentation
+
+Register a communication protocol implementation.
+
+
+**Args**
+
+- **`communication_protocol_type`**: The communication protocol type identifier.
+- **`communication_protocol`**: The communication protocol implementation.
+- **`override`**: Whether to override an existing implementation.
+
+
+
+**Returns**
+
+True if the implementation was registered, False otherwise.
+
+
+---
+
+### Function register_tool_repository(tool_repository_type: str, tool_repository: [Serializer](./../interfaces/serializer.md#serializer)[[ConcurrentToolRepository](./../interfaces/concurrent_tool_repository.md#concurrenttoolrepository)], override: bool) -> bool {#register_tool_repository}
+
+
+Documentation
+
+Register a tool repository implementation.
+
+
+**Args**
+
+- **`tool_repository_type`**: The tool repository type identifier.
+- **`tool_repository`**: The tool repository implementation.
+- **`override`**: Whether to override an existing implementation.
+
+
+
+**Returns**
+
+True if the implementation was registered, False otherwise.
+
+
+---
+
+### Function register_tool_search_strategy(strategy_type: str, strategy: [Serializer](./../interfaces/serializer.md#serializer)[[ToolSearchStrategy](./../interfaces/tool_search_strategy.md#toolsearchstrategy)], override: bool) -> bool {#register_tool_search_strategy}
+
+
+Documentation
+
+Register a tool search strategy implementation.
+
+
+**Args**
+
+- **`strategy_type`**: The tool search strategy type identifier.
+- **`strategy`**: The tool search strategy implementation.
+- **`override`**: Whether to override an existing implementation.
+
+
+
+**Returns**
+
+True if the implementation was registered, False otherwise.
+
+
+---
+
+### Function register_tool_post_processor(tool_post_processor_type: str, tool_post_processor: [Serializer](./../interfaces/serializer.md#serializer)[[ToolPostProcessor](./../interfaces/tool_post_processor.md#toolpostprocessor)], override: bool) -> bool {#register_tool_post_processor}
+
+
+Documentation
+
+Register a tool post processor implementation.
+
+
+**Args**
+
+- **`tool_post_processor_type`**: The tool post processor type identifier.
+- **`tool_post_processor`**: The tool post processor implementation.
+- **`override`**: Whether to override an existing implementation.
+
+
+
+**Returns**
+
+True if the implementation was registered, False otherwise.
+
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/plugins/plugin_loader.md
+================================================================================
+
+---
+title: plugin_loader
+sidebar_label: plugin_loader
+---
+
+# plugin_loader
+
+**File:** `core/src/utcp/plugins/plugin_loader.py`
+
+### Function _load_plugins() {#_load_plugins}
+
+*No function documentation available*
+
+---
+
+### Function ensure_plugins_initialized() {#ensure_plugins_initialized}
+
+*No function documentation available*
+
+---
+
+
+
+================================================================================
+FILE: api/core/utcp/utcp_client.md
+================================================================================
+
+---
+title: utcp_client
+sidebar_label: utcp_client
+---
+
+# utcp_client
+
+**File:** `core/src/utcp/utcp_client.py`
+
+### class UtcpClient {#utcpclient}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async create(cls, root_dir: Optional[str], config: Optional[Union[str, Dict[str, Any], '[UtcpClientConfig](./data/utcp_client_config.md#utcpclientconfig)']]) -> 'UtcpClient'
+
+Create a new instance of UtcpClient.
+
+
+**Args**
+
+- **`root_dir`**: The root directory for the client to resolve relative paths from. Defaults to the current working directory.
+- **`config`**: The configuration for the client. Can be a path to a configuration file, a dictionary, or [UtcpClientConfig](./data/utcp_client_config.md#utcpclientconfig) object.
+- **`tool_repository`**: The tool repository to use. Defaults to [InMemToolRepository](./implementations/in_mem_tool_repository.md#inmemtoolrepository).
+- **`search_strategy`**: The tool search strategy to use. Defaults to TagSearchStrategy.
+
+
+
+**Returns**
+
+A new instance of UtcpClient.
+
+
+
+async register_manual(self, manual_call_template: [CallTemplate](./data/call_template.md#calltemplate)) -> [RegisterManualResult](./data/register_manual_response.md#registermanualresult)
+
+Register a tool [CallTemplate](./data/call_template.md#calltemplate) and its tools.
+
+
+**Args**
+
+- **`manual_call_template`**: The [CallTemplate](./data/call_template.md#calltemplate) to register.
+
+
+
+**Returns**
+
+A [RegisterManualResult](./data/register_manual_response.md#registermanualresult) object containing the registered [CallTemplate](./data/call_template.md#calltemplate) and its tools.
+
+
+
+async register_manuals(self, manual_call_templates: List[[CallTemplate](./data/call_template.md#calltemplate)]) -> List[[RegisterManualResult](./data/register_manual_response.md#registermanualresult)]
+
+Register multiple tool CallTemplates and their tools.
+
+
+**Args**
+
+- **`manual_call_templates`**: List of CallTemplates to register.
+
+
+
+**Returns**
+
+A list of [RegisterManualResult](./data/register_manual_response.md#registermanualresult) objects containing the registered CallTemplates and their tools. Order is not preserved.
+
+
+
+async deregister_manual(self, manual_call_template_name: str) -> bool
+
+Deregister a tool [CallTemplate](./data/call_template.md#calltemplate).
+
+
+**Args**
+
+- **`manual_call_template_name`**: The name of the [CallTemplate](./data/call_template.md#calltemplate) to deregister.
+
+
+
+**Returns**
+
+True if the [CallTemplate](./data/call_template.md#calltemplate) was deregistered, False otherwise.
+
+
+
+async call_tool(self, tool_name: str, tool_args: Dict[str, Any]) -> Any
+
+Call a tool.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to call.
+- **`tool_args`**: The arguments to pass to the tool.
+
+
+
+**Returns**
+
+The result of the tool call.
+
+
+
+async call_tool_streaming(self, tool_name: str, tool_args: Dict[str, Any]) -> AsyncGenerator[Any, None]
+
+Call a tool streamingly.
+
+
+**Args**
+
+- **`tool_name`**: The name of the tool to call.
+- **`tool_args`**: The arguments to pass to the tool.
+
+
+
+**Returns**
+
+An async generator that yields the result of the tool call.
+
+
+
+async search_tools(self, query: str, limit: int, any_of_tags_required: Optional[List[str]]) -> List[[Tool](./data/tool.md#tool)]
+
+Search for tools relevant to the query.
+
+
+**Args**
+
+- **`query`**: The search query.
+- **`limit`**: The maximum number of tools to return. 0 for no limit.
+- **`any_of_tags_required`**: Optional list of tags where one of them must be present in the tool's tags
+
+
+
+**Returns**
+
+A list of tools that match the search query.
+
+
+
+async get_required_variables_for_manual_and_tools(self, manual_call_template: [CallTemplate](./data/call_template.md#calltemplate)) -> List[str]
+
+Get the required variables for a manual [CallTemplate](./data/call_template.md#calltemplate) and its tools.
+
+
+**Args**
+
+- **`manual_call_template`**: The manual [CallTemplate](./data/call_template.md#calltemplate).
+
+
+
+**Returns**
+
+A list of required variables for the manual [CallTemplate](./data/call_template.md#calltemplate) and its tools.
+
+
+
+async get_required_variables_for_registered_tool(self, tool_name: str) -> List[str]
+
+Get the required variables for a registered tool.
+
+
+**Args**
+
+- **`tool_name`**: The name of a registered tool.
+
+
+
+**Returns**
+
+A list of required variables for the tool.
+
+
+---
+
+
+
+================================================================================
+FILE: api/index.md
+================================================================================
+
+---
+title: UTCP API Reference
+sidebar_label: API Specification
+---
+
+# UTCP API Reference
+
+API specification of a UTCP-compliant client implementation. Any implementation of a UTCP Client needs to have all of the classes, functions and fields described in this specification.
+
+This specification is organized by module of the reference python implementation to provide a comprehensive understanding of UTCP's architecture.
+
+**Note:** The modules don't have to be implemented in the same way as in the reference implementation, but all of the functionality here needs to be provided.
+
+**Total documented items:** 195
+**Modules documented:** 41
+
+## Core Modules
+
+Core UTCP framework components that define the fundamental interfaces and implementations.
+
+### [utcp.data.auth](./core\utcp\data\auth.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [utcp.data.auth_implementations.api_key_auth](./core\utcp\data\auth_implementations\api_key_auth.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [utcp.data.auth_implementations.basic_auth](./core\utcp\data\auth_implementations\basic_auth.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [utcp.data.auth_implementations.oauth2_auth](./core\utcp\data\auth_implementations\oauth2_auth.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [utcp.data.call_template](./core\utcp\data\call_template.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [utcp.data.register_manual_response](./core\utcp\data\register_manual_response.md)
+
+- **Contains:** 1 classes
+
+
+### [utcp.data.tool](./core\utcp\data\tool.md)
+
+- **Contains:** 4 classes, 4 methods
+
+
+### [utcp.data.utcp_client_config](./core\utcp\data\utcp_client_config.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [utcp.data.utcp_manual](./core\utcp\data\utcp_manual.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [utcp.data.variable_loader](./core\utcp\data\variable_loader.md)
+
+- **Contains:** 2 classes, 3 methods
+
+
+### [utcp.data.variable_loader_implementations.dot_env_variable_loader](./core\utcp\data\variable_loader_implementations\dot_env_variable_loader.md)
+
+- **Contains:** 2 classes, 3 methods
+
+
+### [utcp.exceptions.utcp_serializer_validation_error](./core\utcp\exceptions\utcp_serializer_validation_error.md)
+
+- **Contains:** 1 classes
+
+
+### [utcp.exceptions.utcp_variable_not_found_exception](./core\utcp\exceptions\utcp_variable_not_found_exception.md)
+
+- **Contains:** 1 classes, 1 methods
+
+
+### [utcp.implementations.default_variable_substitutor](./core\utcp\implementations\default_variable_substitutor.md)
+
+- **Contains:** 1 classes, 2 methods
+
+
+### [utcp.implementations.in_mem_tool_repository](./core\utcp\implementations\in_mem_tool_repository.md)
+
+- **Contains:** 2 classes, 12 methods
+
+
+### [utcp.implementations.post_processors.filter_dict_post_processor](./core\utcp\implementations\post_processors\filter_dict_post_processor.md)
+
+- **Contains:** 2 classes
+
+
+### [utcp.implementations.post_processors.limit_strings_post_processor](./core\utcp\implementations\post_processors\limit_strings_post_processor.md)
+
+- **Contains:** 2 classes
+
+
+### [utcp.implementations.tag_search](./core\utcp\implementations\tag_search.md)
+
+- **Contains:** 2 classes, 3 methods
+
+
+### [utcp.implementations.utcp_client_implementation](./core\utcp\implementations\utcp_client_implementation.md)
+
+- **Contains:** 1 classes, 9 methods
+
+
+### [utcp.interfaces.communication_protocol](./core\utcp\interfaces\communication_protocol.md)
+
+- **Contains:** 1 classes, 4 methods
+
+
+### [utcp.interfaces.concurrent_tool_repository](./core\utcp\interfaces\concurrent_tool_repository.md)
+
+- **Contains:** 1 classes, 10 methods
+
+
+### [utcp.interfaces.serializer](./core\utcp\interfaces\serializer.md)
+
+- **Contains:** 1 classes, 3 methods
+
+
+### [utcp.interfaces.tool_post_processor](./core\utcp\interfaces\tool_post_processor.md)
+
+- **Contains:** 2 classes, 3 methods
+
+
+### [utcp.interfaces.tool_search_strategy](./core\utcp\interfaces\tool_search_strategy.md)
+
+- **Contains:** 2 classes, 3 methods
+
+
+### [utcp.interfaces.variable_substitutor](./core\utcp\interfaces\variable_substitutor.md)
+
+- **Contains:** 1 classes, 2 methods
+
+
+### [utcp.plugins.discovery](./core\utcp\plugins\discovery.md)
+
+- **Contains:** 7 functions
+
+
+### [utcp.plugins.plugin_loader](./core\utcp\plugins\plugin_loader.md)
+
+- **Contains:** 2 functions
+
+
+### [utcp.utcp_client](./core\utcp\utcp_client.md)
+
+- **Contains:** 1 classes, 9 methods
+
+
+## Plugin Modules
+
+Plugin implementations that extend UTCP with specific transport protocols and capabilities.
+
+### [communication_protocols.cli.src.utcp_cli.cli_call_template](./plugins\communication_protocols\cli\src\utcp_cli\cli_call_template.md)
+
+- **Contains:** 3 classes, 2 methods
+
+
+### [communication_protocols.cli.src.utcp_cli.cli_communication_protocol](./plugins\communication_protocols\cli\src\utcp_cli\cli_communication_protocol.md)
+
+- **Contains:** 1 classes, 4 methods
+
+
+### [communication_protocols.http.src.utcp_http.http_call_template](./plugins\communication_protocols\http\src\utcp_http\http_call_template.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [communication_protocols.http.src.utcp_http.http_communication_protocol](./plugins\communication_protocols\http\src\utcp_http\http_communication_protocol.md)
+
+- **Contains:** 1 classes, 4 methods
+
+
+### [communication_protocols.http.src.utcp_http.openapi_converter](./plugins\communication_protocols\http\src\utcp_http\openapi_converter.md)
+
+- **Contains:** 1 classes, 1 methods
+
+
+### [communication_protocols.http.src.utcp_http.sse_call_template](./plugins\communication_protocols\http\src\utcp_http\sse_call_template.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [communication_protocols.http.src.utcp_http.sse_communication_protocol](./plugins\communication_protocols\http\src\utcp_http\sse_communication_protocol.md)
+
+- **Contains:** 1 classes, 4 methods
+
+
+### [communication_protocols.http.src.utcp_http.streamable_http_call_template](./plugins\communication_protocols\http\src\utcp_http\streamable_http_call_template.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [communication_protocols.http.src.utcp_http.streamable_http_communication_protocol](./plugins\communication_protocols\http\src\utcp_http\streamable_http_communication_protocol.md)
+
+- **Contains:** 1 classes, 4 methods
+
+
+### [communication_protocols.mcp.src.utcp_mcp.mcp_call_template](./plugins\communication_protocols\mcp\src\utcp_mcp\mcp_call_template.md)
+
+- **Contains:** 3 classes, 2 methods
+
+
+### [communication_protocols.mcp.src.utcp_mcp.mcp_communication_protocol](./plugins\communication_protocols\mcp\src\utcp_mcp\mcp_communication_protocol.md)
+
+- **Contains:** 1 classes, 3 methods
+
+
+### [communication_protocols.text.src.utcp_text.text_call_template](./plugins\communication_protocols\text\src\utcp_text\text_call_template.md)
+
+- **Contains:** 2 classes, 2 methods
+
+
+### [communication_protocols.text.src.utcp_text.text_communication_protocol](./plugins\communication_protocols\text\src\utcp_text\text_communication_protocol.md)
+
+- **Contains:** 1 classes, 4 methods
+
+
+## About UTCP
+
+The Universal Tool Calling Protocol (UTCP) is a framework for calling tools across various transport protocols.
+This API reference covers all the essential interfaces, implementations, and extension points needed to:
+
+- **Implement** new transport protocols
+- **Extend** UTCP with custom functionality
+- **Integrate** UTCP into your applications
+- **Understand** the complete UTCP architecture
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/cli/src/utcp_cli/cli_call_template.md
+================================================================================
+
+---
+title: cli_call_template
+sidebar_label: cli_call_template
+---
+
+# cli_call_template
+
+**File:** `plugins/communication_protocols/cli/src/utcp_cli/cli_call_template.py`
+
+### class CommandStep {#commandstep}
+
+
+Documentation
+
+Configuration for a single command step in a CLI execution flow.
+
+
+**Attributes**
+
+- **`command`**: The command string to execute. Can contain UTCP_ARG_argname_UTCP_END
+ placeholders that will be replaced with values from tool_args. Can also
+ reference previous command outputs using $CMD_0_OUTPUT, $CMD_1_OUTPUT, etc.
+- **`append_to_final_output`**: Whether this command's output should be included
+ in the final result. If not specified, defaults to False for all
+ commands except the last one.
+
+
+
+**Basic Command Step**
+
+```json
+ {
+ "command": "git status",
+ "append_to_final_output": true
+ }
+```
+
+
+
+**Command With Argument Placeholders And Output Reference**
+
+```json
+ {
+ "command": "echo "Cloning to: UTCP_ARG_target_dir_UTCP_END, previous status: $CMD_0_OUTPUT"",
+ "append_to_final_output": true
+ }
+```
+
+
+#### Fields:
+
+- command: str
+- append_to_final_output: Optional[bool]
+
+---
+
+### class CliCallTemplate ([CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) {#clicalltemplate}
+
+
+Documentation
+
+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. Commands are executed in a single subprocess
+to maintain state (like directory changes) between commands.
+
+
+
+
+**You Can Reference The Output Of Previous Commands Using Variables**
+
+
+- **`Example`**: `echo "Previous result: $CMD_0_OUTPUT"`
+
+
+
+**Attributes**
+
+- **`call_template_type`**: The type of the call template. Must be "cli".
+- **`commands`**: A list of CommandStep objects defining the commands to execute
+ in order. Each command can contain UTCP_ARG_argname_UTCP_END placeholders
+ that will be replaced with values from tool_args during execution.
+- **`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 commands. 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.
+
+
+
+**Cross-Platform Directory Operations**
+
+```json
+ {
+ "name": "cross_platform_dir_tool",
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd UTCP_ARG_target_dir_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "ls -la",
+ "append_to_final_output": true
+ }
+ ]
+ }
+```
+
+
+
+**Referencing Previous Command Output**
+
+```json
+ {
+ "name": "reference_previous_output_tool",
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "git status --porcelain",
+ "append_to_final_output": false
+ },
+ {
+ "command": "echo "Found changes: $CMD_0_OUTPUT"",
+ "append_to_final_output": true
+ }
+ ]
+ }
+```
+
+
+
+**Command With Environment Variables And Placeholders**
+
+```json
+ {
+ "name": "python_multi_step_tool",
+ "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""
+ }
+ ],
+ "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.
+- All placeholders are replaced with string values from tool_args.
+- Commands should use the appropriate syntax for the target platform
+(PowerShell on Windows, Bash on Unix).
+- Previous command outputs are available as variables but should be
+used carefully to avoid command injection.
+
+
+#### Fields:
+
+- call_template_type: Literal['cli']
+- commands: List[CommandStep]
+- env_vars: Optional[Dict[str, str]]
+- working_dir: Optional[str]
+- auth: None
+
+---
+
+### class CliCallTemplateSerializer ([Serializer](./../../../../../core/utcp/interfaces/serializer.md#serializer)[CliCallTemplate]) {#clicalltemplateserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: CliCallTemplate) -> dict
+
+Converts a `CliCallTemplate` instance to its dictionary representation.
+
+
+**Args**
+
+- **`obj`**: The `CliCallTemplate` instance to serialize.
+
+
+
+**Returns**
+
+A dictionary representing the `CliCallTemplate`.
+
+
+
+validate_dict(self, obj: dict) -> CliCallTemplate
+
+Validates a dictionary and constructs a `CliCallTemplate` instance.
+
+
+**Args**
+
+- **`obj`**: The dictionary to validate and deserialize.
+
+
+
+**Returns**
+
+A `CliCallTemplate` instance.
+
+
+
+**Raises**
+
+- **`[UtcpSerializerValidationError](./../../../../../core/utcp/exceptions/utcp_serializer_validation_error.md#utcpserializervalidationerror)`**: If the dictionary is not a valid
+ representation of a `CliCallTemplate`.
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/cli/src/utcp_cli/cli_communication_protocol.md
+================================================================================
+
+---
+title: cli_communication_protocol
+sidebar_label: cli_communication_protocol
+---
+
+# cli_communication_protocol
+
+**File:** `plugins/communication_protocols/cli/src/utcp_cli/cli_communication_protocol.py`
+
+### class CliCommunicationProtocol ([CommunicationProtocol](./../../../../../core/utcp/interfaces/communication_protocol.md#communicationprotocol)) {#clicommunicationprotocol}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async register_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> [RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#registermanualresult)
+
+Registers a CLI-based manual and discovers its tools.
+
+This method executes the command specified in the `[CliCallTemplate](./cli_call_template.md#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](./cli_call_template.md#clicalltemplate)` containing the details for
+ tool discovery, such as the command to run.
+
+
+
+**Returns**
+
+A `[RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#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](./cli_call_template.md#clicalltemplate)` or if `command_name` is not set.
+
+
+
+async deregister_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> None
+
+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.
+
+
+
+async call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> Any
+
+Calls a CLI tool by executing its command.
+
+This method constructs and executes the command specified in the
+`[CliCallTemplate](./cli_call_template.md#clicalltemplate)`. It formats the provided `tool_args` as command-line
+arguments and runs the command in a subprocess.
+
+
+**Args**
+
+- **`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](./cli_call_template.md#clicalltemplate)` for the tool.
+
+
+
+**Returns**
+
+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.
+
+
+
+**Raises**
+
+- **`ValueError`**: If `tool_call_template` is not an instance of
+ `[CliCallTemplate](./cli_call_template.md#clicalltemplate)` or if `command_name` is not set.
+
+
+
+async call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> AsyncGenerator[Any, None]
+
+Streaming calls are not supported for the CLI protocol.
+
+
+**Raises**
+
+- **`NotImplementedError`**: Always, as this functionality is not supported.
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/http/src/utcp_http/http_call_template.md
+================================================================================
+
+---
+title: http_call_template
+sidebar_label: http_call_template
+---
+
+# http_call_template
+
+**File:** `plugins/communication_protocols/http/src/utcp_http/http_call_template.py`
+
+### class HttpCallTemplate ([CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) {#httpcalltemplate}
+
+
+Documentation
+
+Provider configuration for HTTP-based tools.
+
+Supports RESTful HTTP/HTTPS APIs with various HTTP methods, authentication,
+custom headers, and flexible request/response handling. Supports URL path
+parameters using \{parameter_name\} syntax. All tool arguments not mapped to
+URL body, headers or query pattern parameters are passed as query parameters using '?arg_name=\{arg_value\}'.
+
+
+**Basic Http Get Request**
+
+```json
+ {
+ "name": "my_rest_api",
+ "call_template_type": "http",
+ "url": "https://api.example.com/users/{user_id}",
+ "http_method": "GET"
+ }
+```
+
+
+
+**Post With Authentication**
+
+```json
+ {
+ "name": "secure_api",
+ "call_template_type": "http",
+ "url": "https://api.example.com/users",
+ "http_method": "POST",
+ "content_type": "application/json",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${API_KEY}",
+ "var_name": "Authorization",
+ "location": "header"
+ },
+ "headers": {
+ "X-Custom-Header": "value"
+ },
+ "body_field": "body",
+ "header_fields": ["user_id"]
+ }
+```
+
+
+
+**Oauth2 Authentication**
+
+```json
+ {
+ "name": "oauth_api",
+ "call_template_type": "http",
+ "url": "https://api.example.com/data",
+ "http_method": "GET",
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token"
+ }
+ }
+```
+
+
+
+**Basic Authentication**
+
+```json
+ {
+ "name": "basic_auth_api",
+ "call_template_type": "http",
+ "url": "https://api.example.com/secure",
+ "http_method": "GET",
+ "auth": {
+ "auth_type": "basic",
+ "username": "${USERNAME}",
+ "password": "${PASSWORD}"
+ }
+ }
+```
+
+
+
+**Attributes**
+
+- **`call_template_type`**: Always "http" for HTTP providers.
+- **`http_method`**: The HTTP method to use for requests.
+- **`url`**: The base URL for the HTTP endpoint. Supports path parameters like
+ "https://api.example.com/users/{user_id}/posts/{post_id}".
+- **`content_type`**: The Content-Type header for requests.
+- **`auth`**: Optional authentication configuration.
+- **`headers`**: Optional static headers to include in all requests.
+- **`body_field`**: Name of the tool argument to map to the HTTP request body.
+- **`header_fields`**: List of tool argument names to map to HTTP request headers.
+
+
+#### Fields:
+
+- call_template_type: Literal['http']
+- http_method: Literal['GET', 'POST', 'PUT', 'DELETE', 'PATCH']
+- url: str
+- content_type: str
+- auth: Optional[[Auth](./../../../../../core/utcp/data/auth.md#auth)]
+- headers: Optional[Dict[str, str]]
+- body_field: Optional[str]
+- header_fields: Optional[List[str]]
+
+---
+
+### class HttpCallTemplateSerializer ([Serializer](./../../../../../core/utcp/interfaces/serializer.md#serializer)[HttpCallTemplate]) {#httpcalltemplateserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: HttpCallTemplate) -> dict
+
+*No method documentation available*
+
+
+
+validate_dict(self, obj: dict) -> HttpCallTemplate
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/http/src/utcp_http/http_communication_protocol.md
+================================================================================
+
+---
+title: http_communication_protocol
+sidebar_label: http_communication_protocol
+---
+
+# http_communication_protocol
+
+**File:** `plugins/communication_protocols/http/src/utcp_http/http_communication_protocol.py`
+
+### class HttpCommunicationProtocol ([CommunicationProtocol](./../../../../../core/utcp/interfaces/communication_protocol.md#communicationprotocol)) {#httpcommunicationprotocol}
+
+
+Documentation
+
+HTTP communication protocol implementation for UTCP client.
+
+Handles communication with HTTP-based tool providers, supporting various
+authentication methods, URL path parameters, and automatic tool discovery.
+Enforces security by requiring HTTPS or localhost connections.
+
+
+**Features**
+
+- RESTful API communication with configurable HTTP methods
+- URL path parameter substitution from tool arguments
+- [Tool](./../../../../../core/utcp/data/tool.md#tool) discovery from UTCP manuals, OpenAPI specs, and YAML
+- Request body and header field mapping from tool arguments
+- OAuth2 token caching and automatic refresh
+- Security validation of connection URLs
+
+
+
+**Attributes**
+
+- **`_session`**: Optional aiohttp ClientSession for connection reuse.
+- **`_oauth_tokens`**: Cache of OAuth2 tokens by client_id.
+- **`_log`**: Logger function for debugging and error reporting.
+
+
+#### Methods:
+
+
+async register_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> [RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#registermanualresult)
+
+Register a manual and its tools.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`manual_call_template`**: The call template of the manual to register.
+
+
+
+**Returns**
+
+[RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#registermanualresult) object containing the call template and manual.
+
+
+
+async deregister_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> None
+
+*No method documentation available*
+
+
+
+async call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> Any
+
+Execute a tool call through this transport.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`tool_name`**: Name of the tool to call (may include provider prefix).
+- **`tool_args`**: Dictionary of arguments to pass to the tool.
+- **`tool_call_template`**: Call template of the tool to call.
+
+
+
+**Returns**
+
+The tool's response, with type depending on the tool's output schema.
+
+
+
+async call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> AsyncGenerator[Any, None]
+
+Execute a tool call through this transport streamingly.
+
+
+**Args**
+
+- **`caller`**: The UTCP client that is calling this method.
+- **`tool_name`**: Name of the tool to call (may include provider prefix).
+- **`tool_args`**: Dictionary of arguments to pass to the tool.
+- **`tool_call_template`**: Call template of the tool to call.
+
+
+
+**Returns**
+
+An async generator that yields the tool's response.
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/http/src/utcp_http/openapi_converter.md
+================================================================================
+
+---
+title: openapi_converter
+sidebar_label: openapi_converter
+---
+
+# openapi_converter
+
+**File:** `plugins/communication_protocols/http/src/utcp_http/openapi_converter.py`
+
+### class OpenApiConverter {#openapiconverter}
+
+
+Documentation
+
+Converts OpenAPI specifications into UTCP tool definitions.
+
+Processes OpenAPI 2.0 and 3.0 specifications to generate equivalent UTCP
+tools, handling schema resolution, authentication mapping, and proper
+HTTP call_template configuration. Each operation in the OpenAPI spec becomes
+a UTCP tool with appropriate input/output schemas.
+
+
+**Features**
+
+- Complete OpenAPI specification parsing.
+- Recursive JSON reference ($ref) resolution.
+- Authentication scheme conversion (API key, Basic, OAuth2).
+- Input parameter and request body handling.
+- Response schema extraction.
+- URL template and path parameter support.
+- Call template name normalization.
+- Placeholder variable generation for configuration.
+
+
+
+**Basic Openapi Conversion**
+
+```python
+ from utcp_http.openapi_converter import OpenApiConverter
+
+ # Assuming you have a method to fetch and parse the spec
+ openapi_spec = fetch_and_parse_spec("https://api.example.com/openapi.json")
+
+ converter = OpenApiConverter(openapi_spec)
+ manual = converter.convert()
+
+ # Use the generated manual with a UTCP client
+ # client = await UtcpClient.create()
+ # await client.register_manual(manual)
+```
+
+
+
+**Converting Local Openapi File**
+
+```python
+ import yaml
+
+ converter = OpenApiConverter()
+
+
+**With Open("Api_Spec.Yaml", "R") As F**
+
+spec_content = yaml.safe_load(f)
+
+converter = OpenApiConverter(spec_content)
+manual = converter.convert()
+```
+
+
+
+**Architecture**
+
+The converter works by iterating through all paths and operations
+in the OpenAPI spec, extracting relevant information for each
+operation, and creating corresponding UTCP tools with HTTP call_templates.
+
+
+
+**Attributes**
+
+- **`spec`**: The parsed OpenAPI specification dictionary.
+- **`spec_url`**: Optional URL where the specification was retrieved from.
+- **`placeholder_counter`**: Counter for generating unique placeholder variables.
+- **`call_template_name`**: Normalized name for the call_template derived from the spec.
+
+
+#### Methods:
+
+
+convert(self) -> [UtcpManual](./../../../../../core/utcp/data/utcp_manual.md#utcpmanual)
+
+Converts the loaded OpenAPI specification into a [UtcpManual](./../../../../../core/utcp/data/utcp_manual.md#utcpmanual).
+
+This is the main entry point for the conversion process. It iterates through
+the paths and operations in the specification, creating a UTCP tool for each
+one.
+
+
+**Returns**
+
+A [UtcpManual](./../../../../../core/utcp/data/utcp_manual.md#utcpmanual) object containing all the tools generated from the spec.
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/http/src/utcp_http/sse_call_template.md
+================================================================================
+
+---
+title: sse_call_template
+sidebar_label: sse_call_template
+---
+
+# sse_call_template
+
+**File:** `plugins/communication_protocols/http/src/utcp_http/sse_call_template.py`
+
+### class SseCallTemplate ([CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) {#ssecalltemplate}
+
+
+Documentation
+
+Provider configuration for Server-Sent Events (SSE) tools.
+
+Enables real-time streaming of events from server to client using the
+Server-Sent Events protocol. Supports automatic reconnection and
+event type filtering. All tool arguments not mapped to URL body, headers
+or query pattern parameters are passed as query parameters using '?arg_name=\{arg_value\}'.
+
+
+**Attributes**
+
+- **`call_template_type`**: Always "sse" for SSE providers.
+- **`url`**: The SSE endpoint URL to connect to.
+- **`event_type`**: Optional filter for specific event types. If None, all events are received.
+- **`reconnect`**: Whether to automatically reconnect on connection loss.
+- **`retry_timeout`**: Timeout in milliseconds before attempting reconnection.
+- **`auth`**: Optional authentication configuration.
+- **`headers`**: Optional static headers for the initial connection.
+- **`body_field`**: Optional tool argument name to map to request body during connection.
+- **`header_fields`**: List of tool argument names to map to HTTP headers during connection.
+
+
+#### Fields:
+
+- call_template_type: Literal['sse']
+- url: str
+- event_type: Optional[str]
+- reconnect: bool
+- retry_timeout: int
+- auth: Optional[[Auth](./../../../../../core/utcp/data/auth.md#auth)]
+- headers: Optional[Dict[str, str]]
+- body_field: Optional[str]
+- header_fields: Optional[List[str]]
+
+---
+
+### class SSECallTemplateSerializer ([Serializer](./../../../../../core/utcp/interfaces/serializer.md#serializer)[SseCallTemplate]) {#ssecalltemplateserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: SseCallTemplate) -> dict
+
+*No method documentation available*
+
+
+
+validate_dict(self, obj: dict) -> SseCallTemplate
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/http/src/utcp_http/sse_communication_protocol.md
+================================================================================
+
+---
+title: sse_communication_protocol
+sidebar_label: sse_communication_protocol
+---
+
+# sse_communication_protocol
+
+**File:** `plugins/communication_protocols/http/src/utcp_http/sse_communication_protocol.py`
+
+### class SseCommunicationProtocol ([CommunicationProtocol](./../../../../../core/utcp/interfaces/communication_protocol.md#communicationprotocol)) {#ssecommunicationprotocol}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async register_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> [RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#registermanualresult)
+
+*No method documentation available*
+
+
+
+async deregister_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> None
+
+*No method documentation available*
+
+
+
+async call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> Any
+
+*No method documentation available*
+
+
+
+async call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> AsyncGenerator[Any, None]
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/http/src/utcp_http/streamable_http_call_template.md
+================================================================================
+
+---
+title: streamable_http_call_template
+sidebar_label: streamable_http_call_template
+---
+
+# streamable_http_call_template
+
+**File:** `plugins/communication_protocols/http/src/utcp_http/streamable_http_call_template.py`
+
+### class StreamableHttpCallTemplate ([CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) {#streamablehttpcalltemplate}
+
+
+Documentation
+
+Provider configuration for HTTP streaming tools.
+
+Uses HTTP Chunked Transfer Encoding to enable streaming of large responses
+or real-time data. Useful for tools that return large datasets or provide
+progressive results. All tool arguments not mapped to URL body, headers
+or query pattern parameters are passed as query parameters using '?arg_name=\{arg_value\}'.
+
+
+**Attributes**
+
+- **`call_template_type`**: Always "streamable_http" for HTTP streaming providers.
+- **`url`**: The streaming HTTP endpoint URL. Supports path parameters.
+- **`http_method`**: The HTTP method to use (GET or POST).
+- **`content_type`**: The Content-Type header for requests.
+- **`chunk_size`**: Size of each chunk in bytes for reading the stream.
+- **`timeout`**: Request timeout in milliseconds.
+- **`headers`**: Optional static headers to include in requests.
+- **`auth`**: Optional authentication configuration.
+- **`body_field`**: Optional tool argument name to map to HTTP request body.
+- **`header_fields`**: List of tool argument names to map to HTTP request headers.
+
+
+#### Fields:
+
+- call_template_type: Literal['streamable_http']
+- url: str
+- http_method: Literal['GET', 'POST']
+- content_type: str
+- chunk_size: int
+- timeout: int
+- headers: Optional[Dict[str, str]]
+- auth: Optional[[Auth](./../../../../../core/utcp/data/auth.md#auth)]
+- body_field: Optional[str]
+- header_fields: Optional[List[str]]
+
+---
+
+### class StreamableHttpCallTemplateSerializer ([Serializer](./../../../../../core/utcp/interfaces/serializer.md#serializer)[StreamableHttpCallTemplate]) {#streamablehttpcalltemplateserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: StreamableHttpCallTemplate) -> dict
+
+*No method documentation available*
+
+
+
+validate_dict(self, obj: dict) -> StreamableHttpCallTemplate
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/http/src/utcp_http/streamable_http_communication_protocol.md
+================================================================================
+
+---
+title: streamable_http_communication_protocol
+sidebar_label: streamable_http_communication_protocol
+---
+
+# streamable_http_communication_protocol
+
+**File:** `plugins/communication_protocols/http/src/utcp_http/streamable_http_communication_protocol.py`
+
+### class StreamableHttpCommunicationProtocol ([CommunicationProtocol](./../../../../../core/utcp/interfaces/communication_protocol.md#communicationprotocol)) {#streamablehttpcommunicationprotocol}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async register_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> [RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#registermanualresult)
+
+*No method documentation available*
+
+
+
+async deregister_manual(self, caller, manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> None
+
+*No method documentation available*
+
+
+
+async call_tool(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> Any
+
+*No method documentation available*
+
+
+
+async call_tool_streaming(self, caller, tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> AsyncGenerator[Any, None]
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/mcp/src/utcp_mcp/mcp_call_template.md
+================================================================================
+
+---
+title: mcp_call_template
+sidebar_label: mcp_call_template
+---
+
+# mcp_call_template
+
+**File:** `plugins/communication_protocols/mcp/src/utcp_mcp/mcp_call_template.py`
+
+### class McpConfig {#mcpconfig}
+
+
+Documentation
+
+Implementing this class is not required!!!
+The McpCallTemplate just needs to support a MCP compliant server configuration.
+
+Configuration container for multiple MCP servers.
+
+Holds a collection of named MCP server configurations, allowing
+a single MCP provider to manage multiple server connections.
+
+
+**Attributes**
+
+- **`mcpServers`**: Dictionary mapping server names to their configurations.
+
+
+#### Fields:
+
+- mcpServers: Dict[str, Dict[str, Any]]
+
+---
+
+### class McpCallTemplate ([CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) {#mcpcalltemplate}
+
+
+Documentation
+
+Provider configuration for Model Context Protocol (MCP) tools.
+
+Enables communication with MCP servers that provide structured tool
+interfaces. Supports both stdio (local process) and HTTP (remote)
+transport methods.
+
+
+**Basic Mcp Server With Stdio Transport**
+
+```json
+ {
+ "name": "mcp_server",
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {
+ "filesystem": {
+ "command": "node",
+ "args": ["mcp-server.js"],
+ "env": {"NODE_ENV": "production"}
+ }
+ }
+ }
+ }
+```
+
+
+
+**Mcp Server With Working Directory**
+
+```json
+ {
+ "name": "mcp_tools",
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {
+ "tools": {
+ "command": "python",
+ "args": ["-m", "mcp_server"],
+ "cwd": "/app/mcp",
+ "env": {
+ "PYTHONPATH": "/app",
+ "LOG_LEVEL": "INFO"
+ }
+ }
+ }
+ }
+ }
+```
+
+
+
+**Mcp Server With Oauth2 Authentication**
+
+```json
+ {
+ "name": "secure_mcp",
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {
+ "secure_server": {
+ "transport": "http",
+ "url": "https://mcp.example.com"
+ }
+ }
+ },
+ "auth": {
+ "auth_type": "oauth2",
+ "token_url": "https://auth.example.com/token",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "scope": "read:tools"
+ }
+ }
+```
+
+
+
+**During Migration (Utcp With Mcp)**
+
+```python
+ # UTCP Client with MCP plugin
+ client = await UtcpClient.create()
+ result = await client.call_tool("filesystem.read_file", {
+ "path": "/data/file.txt"
+ })
+```
+
+
+
+**After Migration (Pure Utcp)**
+
+```python
+ # UTCP Client with native protocol
+ client = await UtcpClient.create()
+ result = await client.call_tool("filesystem.read_file", {
+ "path": "/data/file.txt"
+ })
+```
+
+
+
+**Attributes**
+
+- **`call_template_type`**: Always "mcp" for MCP providers.
+- **`config`**: Configuration object containing MCP server definitions.
+ This follows the same format as the official MCP server configuration.
+- **`auth`**: Optional OAuth2 authentication for HTTP-based MCP servers.
+- **`register_resources_as_tools`**: Whether to register MCP resources as callable tools.
+ When True, server resources are exposed as tools that can be called.
+ Default is False.
+
+
+#### Fields:
+
+- call_template_type: Literal['mcp']
+- config: McpConfig
+- auth: Optional[[OAuth2Auth](./../../../../../core/utcp/data/auth_implementations/oauth2_auth.md#oauth2auth)]
+- register_resources_as_tools: bool
+
+---
+
+### class McpCallTemplateSerializer ([Serializer](./../../../../../core/utcp/interfaces/serializer.md#serializer)[McpCallTemplate]) {#mcpcalltemplateserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: McpCallTemplate) -> dict
+
+*No method documentation available*
+
+
+
+validate_dict(self, obj: dict) -> McpCallTemplate
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/mcp/src/utcp_mcp/mcp_communication_protocol.md
+================================================================================
+
+---
+title: mcp_communication_protocol
+sidebar_label: mcp_communication_protocol
+---
+
+# mcp_communication_protocol
+
+**File:** `plugins/communication_protocols/mcp/src/utcp_mcp/mcp_communication_protocol.py`
+
+### class McpCommunicationProtocol ([CommunicationProtocol](./../../../../../core/utcp/interfaces/communication_protocol.md#communicationprotocol)) {#mcpcommunicationprotocol}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async register_manual(self, caller: '[UtcpClient](./../../../../../core/utcp/utcp_client.md#utcpclient)', manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> [RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#registermanualresult)
+
+*No method documentation available*
+
+
+
+async call_tool(self, caller: '[UtcpClient](./../../../../../core/utcp/utcp_client.md#utcpclient)', tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> Any
+
+*No method documentation available*
+
+
+
+async call_tool_streaming(self, caller: '[UtcpClient](./../../../../../core/utcp/utcp_client.md#utcpclient)', tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> AsyncGenerator[Any, None]
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/text/src/utcp_text/text_call_template.md
+================================================================================
+
+---
+title: text_call_template
+sidebar_label: text_call_template
+---
+
+# text_call_template
+
+**File:** `plugins/communication_protocols/text/src/utcp_text/text_call_template.py`
+
+### class TextCallTemplate ([CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) {#textcalltemplate}
+
+
+Documentation
+
+Call template for text file-based manuals and tools.
+
+Reads UTCP manuals or tool definitions from local JSON/YAML files. Useful for
+static tool configurations or environments where manuals are distributed as files.
+
+
+**Attributes**
+
+- **`call_template_type`**: Always "text" for text file call templates.
+- **`file_path`**: Path to the file containing the UTCP manual or tool definitions.
+- **`auth`**: Always None - text call templates don't support authentication.
+
+
+#### Fields:
+
+- call_template_type: Literal['text']
+- file_path: str
+- auth: None
+
+---
+
+### class TextCallTemplateSerializer ([Serializer](./../../../../../core/utcp/interfaces/serializer.md#serializer)[TextCallTemplate]) {#textcalltemplateserializer}
+
+*No class documentation available*
+
+#### Methods:
+
+
+to_dict(self, obj: TextCallTemplate) -> dict
+
+*No method documentation available*
+
+
+
+validate_dict(self, obj: dict) -> TextCallTemplate
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: api/plugins/communication_protocols/text/src/utcp_text/text_communication_protocol.md
+================================================================================
+
+---
+title: text_communication_protocol
+sidebar_label: text_communication_protocol
+---
+
+# text_communication_protocol
+
+**File:** `plugins/communication_protocols/text/src/utcp_text/text_communication_protocol.py`
+
+### class TextCommunicationProtocol ([CommunicationProtocol](./../../../../../core/utcp/interfaces/communication_protocol.md#communicationprotocol)) {#textcommunicationprotocol}
+
+*No class documentation available*
+
+#### Methods:
+
+
+async register_manual(self, caller: '[UtcpClient](./../../../../../core/utcp/utcp_client.md#utcpclient)', manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> [RegisterManualResult](./../../../../../core/utcp/data/register_manual_response.md#registermanualresult)
+
+*No method documentation available*
+
+
+
+async deregister_manual(self, caller: '[UtcpClient](./../../../../../core/utcp/utcp_client.md#utcpclient)', manual_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> None
+
+*No method documentation available*
+
+
+
+async call_tool(self, caller: '[UtcpClient](./../../../../../core/utcp/utcp_client.md#utcpclient)', tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> Any
+
+*No method documentation available*
+
+
+
+async call_tool_streaming(self, caller: '[UtcpClient](./../../../../../core/utcp/utcp_client.md#utcpclient)', tool_name: str, tool_args: Dict[str, Any], tool_call_template: [CallTemplate](./../../../../../core/utcp/data/call_template.md#calltemplate)) -> AsyncGenerator[Any, None]
+
+*No method documentation available*
+
+
+---
+
+
+
+================================================================================
+FILE: for-tool-providers.md
+================================================================================
+
+---
+id: for-tool-providers
+title: For Tool Providers
+sidebar_position: 2
+---
+
+# For Tool Providers
+
+:::info Language Note
+This guide covers how to expose your existing APIs and services as UTCP tools. UTCP implementations are available in multiple languages - check the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol) for Python, TypeScript, Go, and other language implementations.
+:::
+
+This guide helps you expose your tools through UTCP so they can be discovered and used by AI agents and other applications.
+
+## Overview
+
+As a tool provider, you'll create a **UTCP Manual** - a standardized description of your tools that tells clients how to call them directly using their native protocols. This eliminates the need for wrapper servers and allows direct communication.
+
+## Quick Start
+
+### 1. Create a Simple Manual
+
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "tools": [
+ {
+ "name": "get_user",
+ "description": "Retrieve user information by ID",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "user_id": {"type": "string", "description": "User identifier"}
+ },
+ "required": ["user_id"]
+ },
+ "outputs": {
+ "type": "object",
+ "properties": {
+ "id": {"type": "string"},
+ "name": {"type": "string"},
+ "email": {"type": "string"}
+ }
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/users/{user_id}",
+ "http_method": "GET"
+ }
+ }
+ ]
+}
+```
+
+### 2. Expose via Discovery Endpoint
+
+Create an HTTP endpoint that returns your UTCP manual:
+
+**Endpoint**: `GET /utcp`
+**Response**:
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "tools": [
+ // ... your tools here
+ ]
+}
+```
+
+Your existing API endpoints remain unchanged. For example:
+- `GET /users/{user_id}` - Returns user data
+- `POST /orders` - Creates new orders
+- etc.
+
+## Manual Structure
+
+The UTCP manual follows a standardized structure that defines your tools and how to call them. For complete field specifications, data types, and validation rules, see the [UTCP Manual API Reference](./api/core/utcp/data/utcp_manual.md).
+
+### Key Components
+
+- **Manual metadata**: Version information and API details
+- **Tool definitions**: Description of available tools and their capabilities
+- **Call templates**: Instructions for invoking each tool
+- **Authentication**: Security configuration for tool access
+- **Variables**: Dynamic values for tool parameters
+
+### Tool Definition
+
+Tools are defined in your UTCP manual with their input parameters, call instructions, and optional metadata. For complete field specifications, see the [Tool API Reference](./api/core/utcp/data/tool.md).
+
+## Communication Protocol Plugins
+
+### HTTP Tools
+
+Most common for REST APIs:
+
+```json
+{
+ "name": "create_user",
+ "description": "Create a new user account",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "user_fields": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "email": {"type": "string", "format": "email"}
+ },
+ "required": ["name", "email"]
+ }
+ },
+ "required": ["user_fields"]
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/users",
+ "http_method": "POST",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${API_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ },
+ "body_field": "user_fields"
+ }
+}
+```
+
+### CLI Tools
+
+For command-line applications:
+
+```json
+{
+ "name": "git_analysis",
+ "description": "Analyze git repository status and commit history",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "repo_path": {"type": "string", "description": "Path to git repository"}
+ },
+ "required": ["repo_path"]
+ },
+ "tool_call_template": {
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd UTCP_ARG_repo_path_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "git status --porcelain",
+ "append_to_final_output": false
+ },
+ {
+ "command": "echo \"Status: $CMD_1_OUTPUT, Files changed: $(echo \"$CMD_1_OUTPUT\" | wc -l)\"",
+ "append_to_final_output": true
+ }
+ ]
+ }
+}
+```
+
+## Authentication
+
+### API Key Authentication
+
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}",
+ "var_name": "X-API-Key",
+ "location": "header"
+ }
+}
+```
+
+### Bearer Token
+
+To use a Bearer Token, you can use the `api_key` authentication type.
+
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${ACCESS_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+}
+```
+
+### OAuth2
+
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "read:users write:users"
+ }
+}
+```
+
+### Per-Tool Authentication
+
+```json
+{
+ "name": "admin_action",
+ "description": "Perform admin action",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/admin/action",
+ "http_method": "POST",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${ADMIN_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+ }
+}
+```
+
+## Variable Substitution
+
+Use `${VARIABLE_NAME}` syntax for dynamic values:
+
+### From Tool Arguments
+
+```json
+{
+ "url": "https://api.example.com/users/{user_id}"
+}
+```
+
+### From Environment Variables
+
+```json
+{
+ "headers": {
+ "Authorization": "Bearer ${API_TOKEN}",
+ "X-Client-ID": "${CLIENT_ID}"
+ }
+}
+```
+
+### Default Values
+
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "variables": {
+ "base_url": "https://api.example.com",
+ "timeout": 30
+ },
+ "tools": [
+ {
+ "name": "get_data",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "${base_url}/data"
+ }
+ }
+ ]
+}
+```
+
+## Implementation Examples
+
+### REST API Implementation
+
+For a typical REST API, you'll need to:
+
+1. **Keep your existing endpoints unchanged**
+2. **Add a UTCP discovery endpoint** at `/utcp`
+3. **Map your API operations to UTCP tools**
+
+Example API structure:
+```
+GET /users/{user_id} # Your existing endpoint
+POST /users # Your existing endpoint
+GET /utcp # New UTCP discovery endpoint
+```
+
+The UTCP manual describes how to call your existing endpoints:
+
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "info": {
+ "title": "User Management API",
+ "version": "1.0.0",
+ "description": "API for managing user accounts"
+ },
+ "tools": [
+ {
+ "name": "get_user",
+ "description": "Retrieve user information by ID",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "user_id": {"type": "string"}
+ },
+ "required": ["user_id"]
+ },
+ "outputs": {
+ "type": "object",
+ "properties": {
+ "id": {"type": "string"},
+ "name": {"type": "string"},
+ "email": {"type": "string"}
+ }
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/users/{user_id}",
+ "http_method": "GET",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${API_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+ }
+ },
+ {
+ "name": "create_user",
+ "description": "Create a new user account",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "email": {"type": "string"}
+ },
+ "required": ["name", "email"]
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/users",
+ "http_method": "POST",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${API_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ },
+ "body_field": "user_data"
+ }
+ }
+ ]
+}
+```
+
+## OpenAPI Integration
+
+If you already have an OpenAPI/Swagger specification, you can automatically convert it to a UTCP manual:
+
+### Automatic Conversion
+
+Many UTCP implementations provide OpenAPI converters that can:
+
+1. **Parse OpenAPI specifications** from URLs or files
+2. **Convert paths to UTCP tools** automatically
+3. **Map authentication schemes** to UTCP auth types
+4. **Generate proper input/output schemas**
+
+### Conversion Configuration
+
+You can customize the conversion process:
+
+```json
+{
+ "source": "https://api.example.com/openapi.json",
+ "base_url": "https://api.example.com",
+ "include_operations": ["get", "post"],
+ "exclude_paths": ["/internal/*"],
+ "auth_template": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}",
+ "var_name": "X-API-Key",
+ "location": "header"
+ }
+}
+```
+
+### Manual Review
+
+After automatic conversion:
+1. **Review generated tools** for accuracy
+2. **Add missing descriptions** and examples
+3. **Validate input/output schemas**
+4. **Test with UTCP clients**
+5. **Customize authentication** as needed
+
+## Best Practices
+
+### Manual Design
+
+1. **Clear Descriptions**: Write clear, concise tool descriptions
+2. **Comprehensive Schemas**: Use detailed JSON schemas for inputs/outputs
+3. **Consistent Naming**: Use consistent naming conventions
+4. **Version Management**: Use semantic versioning for your manual
+5. **Documentation**: Include examples and usage notes
+
+### Security
+
+1. **Authentication**: Always implement proper authentication
+2. **Input Validation**: Validate all inputs on your API side
+3. **Rate Limiting**: Implement rate limiting to prevent abuse
+4. **HTTPS Only**: Use HTTPS for all production endpoints
+5. **Credential Management**: Never hardcode credentials in manuals
+
+### Performance
+
+1. **Efficient Endpoints**: Design efficient API endpoints
+2. **Caching**: Implement appropriate caching strategies
+3. **Pagination**: Use pagination for large result sets
+4. **Timeouts**: Set reasonable timeout values
+5. **Monitoring**: Monitor API performance and usage
+
+### Maintenance
+
+1. **Versioning**: Version your manual and API together
+2. **Backward Compatibility**: Maintain backward compatibility when possible
+3. **Deprecation**: Provide clear deprecation notices
+4. **Testing**: Test your manual with UTCP clients
+5. **Documentation**: Keep documentation up to date
+
+## Testing Your Manual
+
+### Manual Validation
+
+Validate your UTCP manual structure:
+
+1. **JSON Schema Validation**: Ensure your manual follows the UTCP schema
+2. **Tool Definition Validation**: Check that all tools have required fields
+3. **Call Template Validation**: Verify call templates are properly formatted
+4. **Authentication Validation**: Test authentication configurations
+
+### Integration Testing
+
+Test your manual with UTCP clients:
+
+1. **Tool Discovery**: Verify clients can discover your tools
+2. **Tool Execution**: Test actual tool calls with various inputs
+3. **Error Handling**: Test error scenarios and responses
+4. **Authentication**: Verify authentication works correctly
+5. **Performance**: Test response times and reliability
+
+### Testing Checklist
+
+- [ ] Manual validates against UTCP schema
+- [ ] All tools have unique names
+- [ ] All required fields are present
+- [ ] Call templates are correctly formatted
+- [ ] Authentication works as expected
+- [ ] Tools return expected outputs
+- [ ] Error responses are properly formatted
+- [ ] Performance meets requirements
+
+## Migration Strategies
+
+### From OpenAPI
+
+1. **Automatic Conversion**: Use OpenAPI converter for initial conversion
+2. **Manual Refinement**: Refine converted manual for better descriptions
+3. **Authentication Setup**: Configure authentication properly
+4. **Testing**: Test converted manual thoroughly
+
+### From MCP
+
+1. **Wrapper Approach**: Use UTCP-MCP plugin initially
+2. **Gradual Migration**: Migrate tools one by one to native protocols
+3. **Direct Implementation**: Implement tools using native UTCP protocols
+4. **Deprecation**: Remove MCP dependency once migration is complete
+
+## Common Patterns
+
+### CRUD Operations
+
+```json
+{
+ "tools": [
+ {
+ "name": "create_resource",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/resources",
+ "http_method": "POST"
+ }
+ },
+ {
+ "name": "get_resource",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/resources/${id}",
+ "http_method": "GET"
+ }
+ },
+ {
+ "name": "update_resource",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/resources/${id}",
+ "http_method": "PUT"
+ }
+ },
+ {
+ "name": "delete_resource",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/resources/${id}",
+ "http_method": "DELETE"
+ }
+ }
+ ]
+}
+```
+
+### Batch Operations
+
+```json
+{
+ "name": "batch_process",
+ "description": "Process multiple items in batch",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "items": {
+ "type": "array",
+ "items": {"type": "object"}
+ }
+ }
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/batch",
+ "http_method": "POST",
+ "body_field": "items"
+ }
+}
+```
+
+## Next Steps
+
+1. **Design Your Manual**: Plan your tool structure and descriptions
+2. **Choose Protocols**: Select appropriate communication protocols
+3. **Implement Discovery**: Add the `/utcp` endpoint to your API
+4. **Test Integration**: Test with UTCP clients
+5. **Monitor Usage**: Monitor how your tools are being used
+6. **Iterate**: Improve based on usage patterns and feedback
+
+For more information, see:
+- [Communication Protocol Plugins](./protocols/index.md)
+- [Implementation Guide](./implementation.md)
+- [Security Considerations](./security.md)
+
+## Language-Specific Implementation
+
+For detailed implementation examples and code samples in your programming language:
+
+- **Multi-language**: [UTCP Implementation Examples](https://github.com/universal-tool-calling-protocol) - Examples across Python, TypeScript, Go, and other languages
+- **TypeScript**: [TypeScript UTCP Documentation](https://github.com/universal-tool-calling-protocol/typescript-utcp/tree/main/docs)
+- **Other languages**: Check respective repositories in the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol)
+
+
+
+================================================================================
+FILE: implementation.md
+================================================================================
+
+---
+id: implementation
+title: Implementation Guide
+sidebar_position: 4
+---
+
+# UTCP Implementation Guide
+
+This guide covers the core concepts and patterns for implementing UTCP in any programming language, whether you're building tool providers or tool consumers.
+
+## Quick Start
+
+### 1. Install UTCP Library
+
+Choose the UTCP implementation for your programming language:
+
+- **Python**: `pip install utcp utcp-http utcp-cli`
+- **Node.js**: `npm install @utcp/core @utcp/http @utcp/cli`
+- **Other languages**: Check the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol)
+
+### 2. Create Your First Tool Provider
+
+Create an HTTP endpoint that serves a UTCP manual:
+
+**Endpoint**: `GET /utcp`
+**Response**:
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "info": {
+ "title": "Weather API",
+ "version": "1.0.0"
+ },
+ "tools": [
+ {
+ "name": "get_weather",
+ "description": "Get current weather for a location",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "location": {"type": "string"}
+ },
+ "required": ["location"]
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.weather.com/current",
+ "http_method": "GET",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${WEATHER_API_KEY}",
+ "var_name": "appid",
+ "location": "query"
+ }
+ }
+ }
+ ]
+}
+```
+
+### 3. Create Your First Client
+
+Configure a UTCP client to discover and call tools:
+
+**Configuration**:
+```json
+{
+ "manual_call_templates": [
+ {
+ "name": "weather_service",
+ "call_template_type": "http",
+ "url": "https://api.weather.com/utcp",
+ "http_method": "GET"
+ }
+ ],
+ "variables": {
+ "WEATHER_API_KEY": "your-api-key"
+ }
+}
+```
+
+**Usage**:
+1. Initialize UTCP client with configuration
+2. Discover tools from the weather service
+3. Call the `get_weather` tool with location parameter
+
+## Core Concepts
+
+### UTCP Manual
+
+A UTCP manual is a JSON document that describes available tools and how to call them:
+
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "info": {
+ "title": "API Name",
+ "version": "1.0.0",
+ "description": "API description"
+ },
+ "tools": [
+ {
+ "name": "tool_name",
+ "description": "Tool description",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "param": {"type": "string"}
+ }
+ },
+ "outputs": {
+ "type": "object",
+ "properties": {
+ "result": {"type": "string"}
+ }
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/endpoint",
+ "http_method": "POST"
+ }
+ }
+ ]
+}
+```
+
+### Call Templates
+
+Call templates define how to invoke tools using specific protocols:
+
+#### HTTP Call Template
+```json
+{
+ "call_template_type": "http",
+ "url": "https://api.example.com/endpoint",
+ "http_method": "POST",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ },
+ "body_field": "body"
+}
+
+Tool arguments not used in the URL path or headers will be sent as query parameters for GET requests, or in the request body for POST/PUT/PATCH requests. The `body_field` specifies which tool argument contains the data for the request body.
+```
+
+#### CLI Call Template
+```json
+{
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd /app",
+ "append_to_final_output": false
+ },
+ {
+ "command": "python script.py UTCP_ARG_input_UTCP_END",
+ "append_to_final_output": true
+ }
+ ],
+ "env_vars": {
+ "PYTHONPATH": "/app/lib"
+ },
+ "working_dir": "/app"
+}
+```
+
+### Variable Substitution
+
+Variables in call templates are replaced with actual values:
+
+- **Tool arguments**: `${argument_name}`
+- **Environment variables**: `${ENV_VAR}`
+- **Configuration variables**: `${config.variable}`
+
+## Tool Provider Implementation
+
+### Manual Structure
+
+Create a well-structured UTCP manual:
+
+1. **Info Section**: Describe your API
+2. **Tools Array**: Define each available tool
+3. **Input Schemas**: Specify required parameters
+4. **Output Schemas**: Document return values
+5. **Call Templates**: Define how to invoke each tool
+
+### Discovery Endpoint
+
+Expose your manual via HTTP:
+
+```
+GET /utcp
+Content-Type: application/json
+
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "tools": [...]
+}
+```
+
+### Authentication
+
+Support various authentication methods:
+
+#### API Key Authentication
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}",
+ "var_name": "X-API-Key",
+ "location": "header"
+ }
+}
+```
+
+#### OAuth2 Authentication
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token"
+ }
+}
+```
+
+## Tool Consumer Implementation
+
+### Client Configuration
+
+Configure your UTCP client:
+
+#### File-based Configuration
+```yaml
+# utcp-config.yaml
+manual_call_templates:
+ - name: weather_service
+ call_template_type: http
+ url: https://api.weather.com/utcp
+
+variables:
+ WEATHER_API_KEY: your-api-key
+
+load_variables_from:
+ - variable_loader_type: dotenv
+ env_file_path: .env
+```
+
+#### Programmatic Configuration
+```json
+{
+ "manual_call_templates": [
+ {
+ "name": "service_name",
+ "call_template_type": "http",
+ "url": "https://api.example.com/utcp"
+ }
+ ],
+ "variables": {
+ "API_KEY": "your-key"
+ }
+}
+```
+
+### Tool Discovery
+
+Discover available tools:
+
+1. **List Tools**: Get all available tools
+2. **Tool Information**: Get detailed tool metadata
+3. **Filter Tools**: Find tools by name, tags, or description
+
+### Tool Execution
+
+Execute tools with proper error handling:
+
+1. **Basic Calls**: Simple tool invocation
+2. **Batch Calls**: Execute multiple tools
+3. **Context Passing**: Pass context between calls
+4. **Error Handling**: Handle failures gracefully
+
+## Advanced Implementation Patterns
+
+### Custom Protocol Plugins
+
+Extend UTCP with custom communication protocols:
+
+1. **Define Call Template**: Structure for your protocol
+2. **Implement Communication Handler**: Protocol-specific logic
+3. **Register Protocol**: Make it available to clients
+
+Example custom protocol structure:
+```json
+{
+ "call_template_type": "custom",
+ "custom_field": "value",
+ "timeout": 30
+}
+```
+
+### Custom Tool Repositories
+
+Implement custom tool storage:
+
+1. **Tool Storage**: How tools are stored and retrieved
+2. **Search Functionality**: Tool discovery and filtering
+3. **Caching**: Performance optimization
+4. **Synchronization**: Multi-client coordination
+
+### Testing Strategies
+
+#### Unit Testing Tool Providers
+- Test manual generation
+- Validate tool definitions
+- Test authentication
+- Mock external dependencies
+
+#### Integration Testing
+- Test tool discovery
+- Test tool execution
+- Test error scenarios
+- Test performance
+
+#### End-to-End Testing
+- Test complete workflows
+- Test multiple protocols
+- Test real-world scenarios
+- Test scalability
+
+## Best Practices
+
+### Performance
+- Use connection pooling
+- Implement caching
+- Optimize tool discovery
+- Monitor response times
+
+### Security
+- Validate all inputs
+- Use secure authentication
+- Implement rate limiting
+- Log security events
+
+### Reliability
+- Implement retry logic
+- Handle network failures
+- Use circuit breakers
+- Monitor tool health
+
+### Maintainability
+- Version your manuals
+- Document all tools
+- Use consistent naming
+- Provide examples
+
+## Deployment Considerations
+
+### Scaling
+- Load balance tool providers
+- Cache tool discoveries
+- Use async processing
+- Monitor resource usage
+
+### Monitoring
+- Track tool usage
+- Monitor error rates
+- Log performance metrics
+- Set up alerts
+
+### Security
+- Use HTTPS everywhere
+- Implement proper authentication
+- Validate all inputs
+- Monitor for abuse
+
+## Language-Specific Implementation
+
+For detailed implementation examples and code samples in your programming language:
+
+- **Multi-language**: [UTCP Implementation Examples](https://github.com/universal-tool-calling-protocol) - Examples across Python, TypeScript, Go, and other languages
+- **TypeScript**: [TypeScript UTCP Documentation](https://github.com/universal-tool-calling-protocol/typescript-utcp/tree/main/docs)
+- **Other languages**: Check respective repositories in the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol)
+
+For more detailed information, see:
+- [Communication Protocol Plugins](./protocols/index.md)
+- [API Reference](./api/index.md)
+- [Security Considerations](./security.md)
+
+
+
+================================================================================
+FILE: index.md
+================================================================================
+
+---
+id: index
+title: Introduction
+sidebar_position: 1
+---
+
+# Universal Tool Calling Protocol (UTCP)
+
+:::info Language Examples
+UTCP is available in multiple languages - see [Python](https://github.com/universal-tool-calling-protocol/python-utcp), [TypeScript](https://github.com/universal-tool-calling-protocol/typescript-utcp), [Go](https://github.com/universal-tool-calling-protocol/go-utcp), and other implementations in the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol).
+:::
+
+UTCP is a lightweight, secure, and scalable standard that enables AI agents and applications to discover and call tools directly using their native protocols - **no wrapper servers required**.
+
+## Why UTCP?
+
+### The Problem with Current Approaches
+Most tool integration solutions force you to:
+- Build and maintain wrapper servers for every tool
+- Route all traffic through a middleman protocol
+- Reimplement existing authentication and security
+- Accept additional latency and complexity
+
+### The UTCP Solution
+UTCP acts as a **"manual"** that tells agents how to call your tools directly:
+
+:::tip Core Philosophy
+*"If a human can call your API, an AI agent should be able to call it too - with the same security and no additional infrastructure."*
+:::
+
+## OpenAPI Compatibility
+
+UTCP extends OpenAPI for AI agents while maintaining full backward compatibility. Where OpenAPI describes APIs for human developers, UTCP adds agent-focused enhancements: `tags` for categorization, `average_response_size` for resource planning, multi-protocol support (HTTP, CLI, gRPC, MCP), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes or additional infrastructure.
+
+## Quick Start (5 Minutes)
+
+### 1. Install UTCP
+
+```bash
+# Example installation (Python)
+pip install utcp utcp-http
+
+# Example installation (Node.js)
+npm install @utcp/core @utcp/http
+
+# See language-specific documentation for other implementations
+```
+
+### 2. Expose Your First Tool
+
+**Option A: Discovery via existing OpenAPI spec**
+
+**Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json`
+
+
+**Option B: Add a discovery endpoint to your existing API**
+
+**Add endpoint**: `GET /utcp`
+**Return your UTCP manual**:
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "tools": [{
+ "name": "get_weather",
+ "description": "Get current weather for a location",
+ "inputs": {
+ "type": "object",
+ "properties": {"location": {"type": "string"}},
+ "required": ["location"]
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "http://localhost:8000/weather",
+ "http_method": "GET"
+ }
+ }],
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${WEATHER_API_KEY}",
+ "var_name": "appid",
+ "location": "query"
+ }
+}
+```
+
+### 3. Call Your Tool
+
+**Option A: Configure UTCP client**:
+```json
+{
+ "manual_call_templates": [{
+ "name": "weather_api",
+ "call_template_type": "http",
+ "url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically
+ "http_method": "GET"
+ }]
+}
+```
+
+**Option B: Convert OpenAPI spec to UTCP manual manually**
+
+```python
+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
+```
+
+Then save that to a text file and load it with the text configuration:
+```json
+{
+ "manual_call_templates": [{
+ "name": "github_manual",
+ "call_template_type": "text",
+ "file_path": "./github_manual.json",
+ }]
+}
+```
+
+
+**Call the tool**:
+1. Initialize UTCP client with configuration
+2. Discover tools from weather API
+3. Call `get_weather` tool with location parameter
+4. Receive weather data response
+
+**That's it!** Your tool is now discoverable and callable by any UTCP client.
+
+## Key Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| **🚀 Zero Latency Overhead** | Direct tool calls, no proxy servers |
+| **🔒 Native Security** | Use your existing authentication and authorization |
+| **🌐 Protocol Flexibility** | HTTP, MCP, CLI, GraphQL, and more |
+| **⚡ Easy Integration** | Add one endpoint, no infrastructure changes |
+| **📈 Scalable** | Leverage your existing scaling and monitoring |
+
+## How It Works
+
+```mermaid
+graph LR
+ A[AI Agent] -->|1. Discover| B[UTCP Manual]
+ B -->|2. Learn| C[Tool Definitions]
+ A -->|3. Call Directly| D[Your API]
+ D -->|4. Response| A
+```
+
+1. **Discovery**: Agent fetches your UTCP manual
+2. **Learning**: Agent understands how to call your tools
+3. **Direct Calling**: Agent calls your API directly using native protocols
+4. **Response**: Your API responds normally
+
+## Supported Protocols
+
+UTCP supports multiple communication protocols through plugins:
+
+| Protocol | Use Case | Plugin | Status |
+|----------|----------|--------|--------|
+| **[HTTP](./protocols/http.md)** | REST APIs, webhooks | `utcp-http` | ✅ Stable |
+| **[CLI](./protocols/cli.md)** | Command-line tools | `utcp-cli` | ✅ Stable |
+| **[Server-Sent Events](./protocols/streamable-http.md)** | Streaming data | `utcp-http` | ✅ Stable |
+| **[Text Files](./protocols/text.md)** | File reading | `utcp-text` | ✅ Stable |
+| **[MCP](./protocols/mcp.md)** | MCP interoperability | `utcp-mcp` | ✅ Stable |
+
+[View all protocols →](./protocols/index.md)
+
+## Architecture Overview
+
+UTCP v1.0 features a modular, plugin-based architecture:
+
+### Core Components
+- **[Manuals](./api/core/utcp/data/utcp_manual.md)**: Tool definitions and metadata
+- **[Tools](./api/core/utcp/data/tool.md)**: Individual callable capabilities
+- **[Call Templates](./api/core/utcp/data/call_template.md)**: Protocol-specific call instructions
+- **[UTCP Client](./api/core/utcp/utcp_client.md)**: Tool discovery and execution engine
+
+### Plugin System
+- **Protocol Plugins**: HTTP, MCP, CLI, etc.
+- **Custom Protocols**: Extend with your own communication methods
+- **Tool Repositories**: Pluggable storage for tool definitions
+- **Search Strategies**: Customizable tool discovery algorithms
+
+[Learn more about the architecture →](./api/index.md)
+
+## Who Should Use UTCP?
+
+### 🛠️ Tool Providers
+You have APIs, services, or tools that you want AI agents to use:
+- **Existing API owners** - Expose your REST APIs to AI agents
+- **SaaS providers** - Make your services AI-accessible
+- **Enterprise teams** - Enable internal tool usage by AI systems
+
+[**Get started as a tool provider →**](./for-tool-providers.md)
+
+### 🤖 Tool Consumers
+You're building AI agents or applications that need to call external tools:
+- **AI agent developers** - Give your agents access to external capabilities
+- **Application builders** - Integrate third-party tools seamlessly
+- **Enterprise developers** - Connect to internal and external services
+
+[**Get started as a tool consumer →**](./implementation.md)
+
+## UTCP vs Alternatives
+
+| Feature | UTCP | MCP | Custom Wrappers |
+|---------|------|-----|-----------------|
+| **Infrastructure** | None required | Wrapper servers | Custom servers |
+| **Latency** | Direct calls | Double hop | Variable |
+| **Security** | Native | Reimplemented | Custom |
+| **Protocols** | Multiple | HTTP streaming | Single |
+| **Maintenance** | Minimal | High | Very high |
+
+[**Detailed comparison with MCP →**](./utcp-vs-mcp.md)
+
+## Next Steps
+
+### For Tool Providers
+1. **[Read the provider guide](./for-tool-providers.md)** - Learn how to expose your tools
+2. **[Choose your protocol](./protocols/index.md)** - Select the right communication method
+3. **[Implement your manual](./implementation.md)** - Add UTCP to your existing API
+4. **[Secure your tools](./security.md)** - Implement proper authentication
+
+### For Tool Consumers
+1. **[Read the implementation guide](./implementation.md)** - Learn how to build UTCP clients
+2. **[Explore protocols](./protocols/index.md)** - Understand available communication options
+3. **[Check examples](https://github.com/universal-tool-calling-protocol)** - See real-world implementations
+4. **[Join the community](https://discord.gg/ZpMbQ8jRbD)** - Get help and share experiences
+
+### Migration from Other Systems
+- **[From UTCP v0.1](./migration-v0.1-to-v1.0.md)** - Upgrade to the latest version
+- **[From MCP](./protocols/mcp.md)** - Migrate from Model Context Protocol
+- **[From custom solutions](./implementation.md)** - Replace existing tool integrations
+
+## Community & Support
+
+- **[GitHub Organization](https://github.com/universal-tool-calling-protocol)** - Source code and issues
+- **[Discord Community](https://discord.gg/ZpMbQ8jRbD)** - Real-time help and discussions
+- **[Tool Registry](https://utcp.io/registry)** - Discover available tools
+- **[RFC Process](/about/RFC)** - Contribute to the specification
+
+---
+
+**Ready to get started?** Choose your path:
+- 🛠️ [**I want to expose my tools**](./for-tool-providers.md)
+- 🤖 [**I want to call tools**](./implementation.md)
+- 📚 [**I want to learn more**](./protocols/index.md)
+
+
+
+================================================================================
+FILE: migration-v0.1-to-v1.0.md
+================================================================================
+
+---
+id: migration-v0.1-to-v1.0
+title: Migration Guide - v0.1 to v1.0
+sidebar_position: 7
+---
+
+# Migration Guide: v0.1 to v1.0
+
+This guide helps you migrate from UTCP v0.1 to v1.0, which introduces significant architectural improvements and new features.
+
+## Overview of Changes
+
+### Major Changes in v1.0
+
+1. **Plugin Architecture**: Core functionality split into pluggable components
+2. **Improved Data Models**: Enhanced Pydantic models with better validation
+3. **New Protocol Support**: Additional communication protocols
+4. **Better Error Handling**: More specific exception types
+5. **Enhanced Authentication**: Expanded authentication options
+6. **Performance Improvements**: Optimized client and protocol implementations
+
+### Breaking Changes
+
+| Component | v0.1 | v1.0 | Impact |
+|-----------|------|------|--------|
+| **Package Structure** | Single package | Core + plugins | High |
+| **Client API** | `UtcpClient()` | `UtcpClient.create()` | Medium |
+| **Configuration** | Simple dict | Structured config | Medium |
+| **Protocol Registration** | Automatic | Plugin-based | High |
+| **Error Types** | Generic exceptions | Specific exception types | Low |
+
+## Installation Changes
+
+### v0.1 Installation
+
+```bash
+pip install utcp
+```
+
+### v1.0 Installation
+
+```bash
+# Core package
+pip install utcp
+
+# Protocol plugins (install as needed)
+pip install utcp-http utcp-cli utcp-websocket utcp-text utcp-mcp
+```
+
+## Client Migration
+
+### v0.1 Client Code
+
+**Legacy v0.1 client configuration:**
+- Import UTCP client library
+- Configure providers with provider-specific settings (name, type, URL, HTTP method)
+- Call tools using provider.tool_name format
+- Synchronous tool calling interface
+
+### v1.0 Client Code
+
+**New v1.0 client configuration:**
+- Import updated UTCP client library from new module path
+- Use async factory method for client creation
+- Configure manual call templates instead of providers
+- Use async/await pattern for tool calling
+- Enhanced error handling and response processing
+
+## Configuration Migration
+
+### v0.1 Configuration
+
+```yaml
+providers:
+ - name: weather_service
+ provider_type: http
+ url: https://weather.example.com/utcp
+ http_method: GET
+ - name: file_service
+ provider_type: cli
+ command: cat
+ args: ["${filename}"]
+
+variables:
+ API_KEY: your_api_key
+```
+
+### v1.0 Configuration
+
+```yaml
+manual_call_templates:
+ - name: weather_service
+ call_template_type: http
+ url: https://weather.example.com/utcp
+ http_method: GET
+ - name: file_service
+ call_template_type: cli
+ command: cat
+ args: ["${filename}"]
+
+load_variables_from:
+ - variable_loader_type: dotenv
+ env_file_path: .env
+```
+
+## Manual Format Migration
+
+### v0.1 Manual Format
+
+```json
+{
+ "utcp_version": "0.1.0",
+ "provider_info": {
+ "name": "weather_api",
+ "version": "1.0.0"
+ },
+ "tools": [
+ {
+ "name": "get_weather",
+ "description": "Get weather data",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "location": {"type": "string"}
+ }
+ },
+ "provider": {
+ "provider_type": "http",
+ "url": "https://api.weather.com/current",
+ "method": "GET"
+ }
+ }
+ ]
+}
+```
+
+### v1.0 Manual Format
+
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "0.2.0",
+ "info": {
+ "title": "Weather API",
+ "version": "1.0.0",
+ "description": "Weather data and forecasting tools"
+ },
+ "tools": [
+ {
+ "name": "get_weather",
+ "description": "Get weather data",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "location": {"type": "string"}
+ },
+ "required": ["location"]
+ },
+ "outputs": {
+ "type": "object",
+ "properties": {
+ "temperature": {"type": "number"},
+ "conditions": {"type": "string"}
+ }
+ },
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.weather.com/current",
+ "http_method": "GET",
+ },
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}",
+ "var_name": "appid",
+ "location": "query"
+ }
+ }
+ ]
+}
+```
+
+## Protocol Migration
+
+### HTTP Protocol Changes
+
+#### v0.1 HTTP Provider
+
+```json
+{
+ "provider_type": "http",
+ "url": "https://api.example.com/endpoint",
+ "method": "POST",
+ "headers": {"Authorization": "Bearer ${TOKEN}"},
+ "body": {"data": "${input}"}
+}
+```
+
+#### v1.0 HTTP Call Template
+
+```json
+{
+ "call_template_type": "http",
+ "url": "https://api.example.com/endpoint",
+ "http_method": "POST",
+ "headers": {"Authorization": "Bearer ${TOKEN}"},
+ "body_field": "body",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+}
+```
+
+### CLI Protocol Changes
+
+#### v0.1 CLI Provider
+
+```json
+{
+ "provider_type": "cli",
+ "command": "python",
+ "args": ["script.py", "${input}"],
+ "cwd": "/app"
+}
+```
+
+#### v1.0 CLI Call Template
+
+```json
+{
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd /app",
+ "append_to_final_output": false
+ },
+ {
+ "command": "python script.py UTCP_ARG_input_UTCP_END",
+ "append_to_final_output": true
+ }
+ ],
+ "working_dir": "/app",
+ "env_vars": {
+ "PYTHONPATH": "/app/lib"
+ }
+}
+```
+
+## Authentication Migration
+
+### v0.1 Authentication
+
+```json
+{
+ "provider": {
+ "provider_type": "http",
+ "url": "https://api.example.com/data",
+ "headers": {
+ "Authorization": "Bearer ${API_TOKEN}"
+ }
+ }
+}
+```
+
+### v1.0 Authentication
+
+```json
+{
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/data",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+ }
+}
+```
+
+## Error Handling Migration
+
+### v0.1 Error Handling
+
+**Basic error handling in v0.1:**
+- Simple try/catch block with generic Exception handling
+- Limited error information and context
+- Basic error message printing
+
+### v1.0 Error Handling
+
+**Enhanced error handling in v1.0:**
+- Import specific exception types from utcp.exceptions module
+- Handle ToolNotFoundError for missing tools
+- Handle AuthenticationError for auth failures
+- Handle ToolCallError for tool execution failures
+- Handle base UtcpError for general UTCP errors
+- Use try/catch blocks with specific exception handling
+
+## Step-by-Step Migration
+
+### Step 1: Update Dependencies
+
+```bash
+# Uninstall old version
+pip uninstall utcp
+
+# Install new version with plugins
+pip install utcp utcp-http utcp-cli utcp-websocket utcp-text
+```
+
+### Step 2: Update Client Code
+
+**Migration to async pattern:**
+- **Before**: Synchronous client creation and tool calls
+- **After**: Async client factory method and async tool calls
+- Import asyncio module for async execution
+- Use async/await keywords for client creation and tool calls
+- Run async main function with asyncio.run()
+
+### Step 3: Update Configuration
+
+**Configuration migration helper:**
+- Create migration function to convert v0.1 config to v1.0 format
+- Transform providers array to manual_call_templates array
+- Add variable_loaders configuration for environment variables
+- Map provider_type to call_template_type
+- Migrate HTTP provider settings (URL, method, headers, body)
+- Migrate CLI provider settings (command, args, working_directory)
+- Load old configuration and apply migration helper
+- Create new client with migrated configuration
+
+### Step 4: Update Manual Format
+
+**Manual migration helper:**
+- Create migration function to convert v0.1 manual to v1.0 format
+- Update manual_version and utcp_version fields
+- Transform provider_info to info structure (title, version, description)
+- Migrate tools array with updated structure
+- Convert tool parameters to inputs field
+- Transform provider configuration to tool_call_template
+- Map provider_type to call_template_type
+- Migrate HTTP provider settings (URL, method, headers, body)
+
+### Step 5: Test Migration
+
+**Testing migrated client:**
+- Import pytest and UtcpClient for async testing
+- Create test function with pytest.mark.asyncio decorator
+- Test client creation with migrated configuration
+- Test tool discovery functionality (list_tools)
+- Test tool calling with sample parameters
+- Assert expected results and functionality
+
+## Common Migration Issues
+
+### Issue 1: Async/Await
+
+**Problem**: v1.0 client methods are async
+**Solution**: Add `async`/`await` keywords
+
+**Code changes:**
+- **Before**: Synchronous tool calling (result = client.call_tool("tool", args))
+- **After**: Async tool calling (result = await client.call_tool("tool", args))
+
+### Issue 2: Configuration Format
+
+**Problem**: Configuration structure changed
+**Solution**: Use migration helper or update manually
+
+**Configuration changes:**
+- **Before**: Use "providers" array in configuration
+- **After**: Use "manual_call_templates" array in configuration
+
+### Issue 3: Plugin Dependencies
+
+**Problem**: Protocol implementations not found
+**Solution**: Install required plugins
+
+```bash
+pip install utcp-http utcp-cli utcp-websocket
+```
+
+### Issue 4: Manual Format
+
+**Problem**: Old manual format not recognized
+**Solution**: Update manual structure
+
+```json
+// Before
+{"provider": {"provider_type": "http"}}
+
+// After
+{"tool_call_template": {"call_template_type": "http"}}
+```
+
+## Validation Tools
+
+### Configuration Validator
+
+**Configuration validation helper:**
+- Import UtcpClientConfig from utcp.data.utcp_client_config
+- Create validation function that accepts configuration dictionary
+- Use UtcpClientConfig constructor to validate configuration structure
+- Handle validation exceptions and provide error messages
+- Return validated config object or None on failure
+
+### Manual Validator
+
+**Manual validation helper:**
+- Import UtcpManual from utcp.data.utcp_manual
+- Create validation function that accepts manual dictionary
+- Use UtcpManual constructor to validate manual structure
+- Handle validation exceptions and provide error messages
+- Return validated manual object or None on failure
+
+## Best Practices for Migration
+
+1. **Gradual Migration**: Migrate one component at a time
+2. **Test Thoroughly**: Test each migrated component
+3. **Backup Configurations**: Keep backups of v0.1 configurations
+4. **Use Validation**: Validate configurations and manuals
+5. **Monitor Performance**: Check for performance regressions
+6. **Update Documentation**: Update internal documentation
+7. **Train Team**: Ensure team understands new patterns
+
+## Post-Migration Checklist
+
+- [ ] All dependencies updated
+- [ ] Client code uses async/await
+- [ ] Configuration format updated
+- [ ] Manual format updated
+- [ ] Error handling updated
+- [ ] Tests passing
+- [ ] Performance acceptable
+- [ ] Documentation updated
+- [ ] Team trained on changes
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. **Check Documentation**: Review the [Implementation Guide](./implementation.md)
+2. **GitHub Issues**: Search existing issues or create new ones
+3. **Discord Community**: Join the [UTCP Discord](https://discord.gg/ZpMbQ8jRbD)
+4. **Examples**: Check the [examples repository](https://github.com/universal-tool-calling-protocol) for implementations across multiple languages
+
+## Rollback Plan
+
+If migration issues occur, you can rollback:
+
+```bash
+# Rollback to v0.1
+pip uninstall utcp utcp-http utcp-cli utcp-websocket utcp-text
+pip install utcp==0.1.0
+
+# Restore old configuration files
+cp config-v0.1-backup.yaml config.yaml
+```
+
+Remember to test the rollback process in a non-production environment first.
+
+
+
+================================================================================
+FILE: protocols/cli.md
+================================================================================
+
+---
+id: cli
+title: CLI Protocol
+sidebar_position: 4
+---
+
+# CLI Protocol
+
+The CLI protocol plugin (`utcp-cli`) enables UTCP to execute multi-command workflows and scripts. This protocol supports sequential command execution with state preservation and cross-platform compatibility.
+
+## Installation
+
+```bash
+# Example installation (Python)
+pip install utcp-cli
+
+# Example installation (Node.js)
+npm install @utcp/cli
+```
+
+## Key Features
+
+- **Multi-Command Execution**: Execute multiple commands sequentially in a single subprocess
+- **State Preservation**: Directory changes and environment persist between commands
+- **Cross-Platform Script Generation**: PowerShell on Windows, Bash on Unix/Linux/macOS
+- **Flexible Output Control**: Choose which command outputs to include in final result
+- **Argument Substitution**: `UTCP_ARG_argname_UTCP_END` placeholder system
+- **Output Referencing**: Access previous command outputs with `$CMD_0_OUTPUT`, `$CMD_1_OUTPUT`
+- **Environment Variables**: Secure credential and configuration passing
+
+## Call Template Structure
+
+```json
+{
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd UTCP_ARG_target_dir_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "git status --porcelain",
+ "append_to_final_output": false
+ },
+ {
+ "command": "echo \"Status: $CMD_1_OUTPUT, Files: $(echo \"$CMD_1_OUTPUT\" | wc -l)\"",
+ "append_to_final_output": true
+ }
+ ],
+ "working_dir": "/tmp",
+ "env_vars": {
+ "GIT_AUTHOR_NAME": "UTCP Bot"
+ }
+}
+```
+
+## Configuration Options
+
+### Required Fields
+
+- **`call_template_type`**: Must be `"cli"`
+- **`commands`**: Array of `CommandStep` objects defining the sequence of commands
+
+### Optional Fields
+
+- **`working_dir`**: Working directory for command execution
+- **`env_vars`**: Environment variables to set for all commands
+
+### CommandStep Object
+
+- **`command`**: Command string with `UTCP_ARG_argname_UTCP_END` placeholders
+- **`append_to_final_output`**: Whether to include this command's output in the final result (defaults to `false` for all except the last command)
+
+For complete field specifications and validation rules, see the [CLI Call Template API Reference](../api/plugins/communication_protocols/cli/src/utcp_cli/cli_call_template.md).
+
+## Argument Substitution
+
+Use `UTCP_ARG_argname_UTCP_END` placeholders in command strings:
+
+```json
+{
+ "command": "git clone UTCP_ARG_repo_url_UTCP_END UTCP_ARG_target_dir_UTCP_END"
+}
+```
+
+## Output Referencing
+
+Reference previous command outputs using `$CMD_N_OUTPUT` variables:
+
+```json
+{
+ "commands": [
+ {
+ "command": "git status --porcelain",
+ "append_to_final_output": false
+ },
+ {
+ "command": "echo \"Changes detected: $CMD_0_OUTPUT\"",
+ "append_to_final_output": true
+ }
+ ]
+}
+```
+
+## Security Considerations
+
+:::danger Security Warning
+CLI protocol executes commands on the local system. Always validate inputs and use with caution.
+:::
+
+### Input Validation
+
+Always validate and sanitize inputs to prevent command injection:
+
+```json
+{
+ "name": "safe_file_read",
+ "description": "Safely read a file",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "filename": {
+ "type": "string",
+ "pattern": "^[a-zA-Z0-9._-]+$"
+ }
+ },
+ "required": ["filename"]
+ },
+ "tool_call_template": {
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd /safe/directory",
+ "append_to_final_output": false
+ },
+ {
+ "command": "cat UTCP_ARG_filename_UTCP_END",
+ "append_to_final_output": true
+ }
+ ],
+ "working_dir": "/safe/directory"
+ }
+}
+```
+
+### Sandboxing
+
+Consider running CLI tools in sandboxed environments:
+
+```json
+{
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "docker run --rm --read-only -v /safe/data:/data:ro alpine:latest cat /data/UTCP_ARG_filename_UTCP_END",
+ "append_to_final_output": true
+ }
+ ]
+}
+```
+
+## Examples
+
+### Simple Command Execution
+
+```json
+{
+ "name": "get_system_info",
+ "description": "Get system information",
+ "inputs": {
+ "type": "object",
+ "properties": {}
+ },
+ "tool_call_template": {
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "uname -a",
+ "append_to_final_output": true
+ }
+ ]
+ }
+}
+```
+
+### Multi-Step File Analysis
+
+```json
+{
+ "name": "analyze_directory",
+ "description": "Analyze files in a directory",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "string",
+ "description": "Directory path to analyze"
+ }
+ },
+ "required": ["path"]
+ },
+ "tool_call_template": {
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd UTCP_ARG_path_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "find . -type f | wc -l",
+ "append_to_final_output": false
+ },
+ {
+ "command": "du -sh .",
+ "append_to_final_output": false
+ },
+ {
+ "command": "echo \"Directory Analysis: $CMD_2_OUTPUT total size, $CMD_1_OUTPUT files\"",
+ "append_to_final_output": true
+ }
+ ]
+ }
+}
+```
+
+### Git Workflow
+
+```json
+{
+ "name": "git_analysis",
+ "description": "Analyze git repository",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "repo_url": {"type": "string"},
+ "target_dir": {"type": "string"}
+ },
+ "required": ["repo_url", "target_dir"]
+ },
+ "tool_call_template": {
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "git clone UTCP_ARG_repo_url_UTCP_END UTCP_ARG_target_dir_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "cd UTCP_ARG_target_dir_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "git log --oneline -10",
+ "append_to_final_output": true
+ },
+ {
+ "command": "find . -name '*.py' | wc -l",
+ "append_to_final_output": false
+ },
+ {
+ "command": "echo \"Repository has $CMD_3_OUTPUT Python files\"",
+ "append_to_final_output": true
+ }
+ ],
+ "env_vars": {
+ "GIT_AUTHOR_NAME": "UTCP Bot",
+ "GIT_AUTHOR_EMAIL": "bot@utcp.dev"
+ }
+ }
+}
+```
+
+### Python Development Pipeline
+
+```json
+{
+ "name": "python_pipeline",
+ "description": "Run Python development pipeline",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "project_dir": {"type": "string"},
+ "script_name": {"type": "string"}
+ },
+ "required": ["project_dir", "script_name"]
+ },
+ "tool_call_template": {
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd UTCP_ARG_project_dir_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "python -m pip install -r requirements.txt",
+ "append_to_final_output": false
+ },
+ {
+ "command": "python UTCP_ARG_script_name_UTCP_END",
+ "append_to_final_output": true
+ }
+ ],
+ "working_dir": "/workspace",
+ "env_vars": {
+ "PYTHONPATH": "/workspace/lib",
+ "VIRTUAL_ENV": "/workspace/venv"
+ }
+ }
+}
+```
+
+## Output Handling
+
+The CLI protocol executes all commands in a single subprocess and returns the combined output based on `append_to_final_output` settings:
+
+- Commands with `append_to_final_output: true` contribute to the final result
+- Commands with `append_to_final_output: false` are executed for side effects only
+- If no `append_to_final_output` is specified, only the last command's output is returned
+- JSON output is automatically parsed if detected
+
+### Success Response
+
+```json
+"Directory Analysis: 2.1G total size, 1247 files"
+```
+
+### JSON Output Detection
+
+If output starts with `{` or `[`, it's automatically parsed as JSON:
+
+```json
+{
+ "files": 1247,
+ "size": "2.1G",
+ "analysis_time": "2023-12-01T10:30:00Z"
+}
+```
+
+## Environment Variables
+
+Set environment variables for all commands:
+
+```json
+{
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "node app.js",
+ "append_to_final_output": true
+ }
+ ],
+ "env_vars": {
+ "NODE_ENV": "production",
+ "API_KEY": "${API_KEY}",
+ "PORT": "3000"
+ }
+}
+```
+
+## Working Directory
+
+Specify the initial working directory:
+
+```json
+{
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "make build",
+ "append_to_final_output": true
+ }
+ ],
+ "working_dir": "/project/src"
+}
+```
+
+## Cross-Platform Considerations
+
+### Command Syntax
+
+Commands should use appropriate syntax for the target platform:
+
+**Windows (PowerShell):**
+```json
+{
+ "commands": [
+ {"command": "Get-ChildItem UTCP_ARG_path_UTCP_END"},
+ {"command": "Set-Location UTCP_ARG_dir_UTCP_END"}
+ ]
+}
+```
+
+**Unix/Linux/macOS (Bash):**
+```json
+{
+ "commands": [
+ {"command": "ls -la UTCP_ARG_path_UTCP_END"},
+ {"command": "cd UTCP_ARG_dir_UTCP_END"}
+ ]
+}
+```
+
+### Universal Commands
+
+Some commands work across platforms:
+```json
+{
+ "commands": [
+ {"command": "git status"},
+ {"command": "python --version"},
+ {"command": "node -v"}
+ ]
+}
+```
+
+## Best Practices
+
+1. **Validate Inputs**: Always validate and sanitize user inputs using JSON Schema patterns
+2. **Use Absolute Paths**: Prefer absolute paths for commands and files when possible
+3. **Control Output**: Use `append_to_final_output` to control which command outputs are returned
+4. **Reference Previous Output**: Use `$CMD_N_OUTPUT` to reference previous command results
+5. **Limit Permissions**: Run with minimal necessary permissions
+6. **Sandbox Execution**: Use containers or chroot when possible
+7. **Handle Cross-Platform**: Consider platform-specific command syntax
+8. **Environment Variables**: Use `env_vars` for secure credential passing
+
+## Common Use Cases
+
+- **Multi-step Builds**: setup → compile → test → package
+- **Git Workflows**: clone → analyze → commit → push
+- **Data Pipelines**: fetch → transform → validate → output
+- **File Operations**: navigate → search → process → report
+- **Development Tools**: install dependencies → run tests → generate docs
+- **System Administration**: check status → backup → cleanup → verify
+
+## Error Handling
+
+| Error Type | Description | Handling |
+|------------|-------------|---------|
+| Missing Arguments | Required UTCP_ARG placeholder not provided | Validation error |
+| Command Not Found | Command doesn't exist | Script execution error |
+| Permission Denied | Insufficient permissions | Script execution error |
+| Timeout | Script exceeded timeout | Async timeout error |
+| Non-zero Exit | Script failed | Return stderr output |
+
+## Testing CLI Tools
+
+```python
+import pytest
+from utcp.utcp_client import UtcpClient
+
+@pytest.mark.asyncio
+async def test_multi_command_cli_tool():
+ client = await UtcpClient.create(config={
+ "manual_call_templates": [{
+ "name": "test_cli",
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "echo UTCP_ARG_message_UTCP_END",
+ "append_to_final_output": false
+ },
+ {
+ "command": "echo \"Previous: $CMD_0_OUTPUT\""
+ }
+ ]
+ }]
+ })
+
+ result = await client.call_tool("test_cli.echo_chain", {"message": "hello"})
+ assert "Previous: hello" in result
+```
+
+
+
+================================================================================
+FILE: protocols/http.md
+================================================================================
+
+---
+id: http
+title: HTTP Protocol
+sidebar_position: 1
+---
+
+# HTTP Protocol Plugin
+
+The HTTP protocol plugin enables UTCP to call tools via HTTP/HTTPS requests. This is the most commonly used protocol for REST APIs, webhooks, and web services.
+
+## Call Template Structure
+
+```json
+{
+ "call_template_type": "http",
+ "url": "https://api.example.com/users/{user_id}",
+ "http_method": "GET|POST|PUT|DELETE|PATCH",
+ "content_type": "application/json",
+ "headers": {
+ "X-Custom-Header": "static_value"
+ },
+ "body_field": "body",
+ "header_fields": ["user_agent", "request_id"],
+ "auth": {
+ "auth_type": "api_key|basic|oauth2",
+ "api_key": "${API_KEY}",
+ "var_name": "Authorization",
+ "location": "header|query|cookie"
+ }
+}
+```
+
+### Field Descriptions
+
+For detailed field descriptions, examples, and implementation details, see:
+- **[HttpCallTemplate API Reference](../api/plugins/communication_protocols/http/src/utcp_http/http_call_template.md)** - Complete field documentation with examples
+- **[HttpCommunicationProtocol API Reference](../api/plugins/communication_protocols/http/src/utcp_http/http_communication_protocol.md)** - Implementation details and method documentation
+
+## Supported HTTP Methods
+
+| Method | Use Case | Body Support |
+|--------|----------|--------------|
+| `GET` | Retrieve data | No |
+| `POST` | Create resources, submit data | Yes |
+| `PUT` | Update/replace resources | Yes |
+| `PATCH` | Partial updates | Yes |
+| `DELETE` | Remove resources | Optional |
+
+## Authentication Methods
+
+### API Key Authentication
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}",
+ "var_name": "X-API-Key",
+ "location": "header|query|cookie"
+ }
+}
+```
+
+Supported locations:
+- `"header"`: API key sent as HTTP header
+- `"query"`: API key sent as query parameter
+- `"cookie"`: API key sent as HTTP cookie
+
+### Basic Authentication
+```json
+{
+ "auth": {
+ "auth_type": "basic",
+ "username": "${USERNAME}",
+ "password": "${PASSWORD}"
+ }
+}
+```
+
+### OAuth2 Authentication
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "read write"
+ }
+}
+```
+
+## Parameter Handling
+
+The HTTP protocol handles tool arguments in a hierarchical manner:
+
+1. **URL Path Parameters**: Arguments matching `{param_name}` in the URL are substituted directly
+2. **Body Field**: If `body_field` is specified, that argument becomes the request body
+3. **Header Fields**: Arguments listed in `header_fields` become request headers
+4. **Query Parameters**: All remaining arguments become query parameters
+
+### URL Path Parameters
+URL templates can include path parameters using `{parameter_name}` syntax:
+
+```json
+{
+ "url": "https://api.example.com/users/{user_id}/posts/{post_id}"
+}
+```
+
+When calling a tool with arguments `{"user_id": "123", "post_id": "456", "limit": "10"}`, the URL becomes:
+`https://api.example.com/users/123/posts/456?limit=10`
+
+### Body Field Mapping
+Specify which tool argument should be sent as the request body:
+
+```json
+{
+ "body_field": "data",
+ "content_type": "application/json"
+}
+```
+
+### Header Field Mapping
+Map specific tool arguments to HTTP headers:
+
+```json
+{
+ "header_fields": ["user_agent", "request_id"]
+}
+```
+
+Tool arguments `user_agent` and `request_id` will be sent as HTTP headers.
+
+### Variable Substitution in Authentication
+Authentication fields support environment variable substitution:
+
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${API_KEY}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+}
+```
+
+## OpenAPI Integration
+
+The HTTP communication protocol automatically detects and converts OpenAPI/Swagger specifications to UTCP manuals:
+
+### Automatic Detection
+When registering an HTTP provider, the protocol:
+1. Fetches content from the specified URL
+2. Checks if the response contains `utcp_version` and `tools` fields (UTCP manual)
+3. If not, assumes it's an OpenAPI specification and converts it automatically
+
+### Conversion Process
+The `OpenApiConverter` handles:
+- **Path Mapping**: OpenAPI paths become UTCP tool URLs with path parameters
+- **Method Mapping**: HTTP methods are preserved
+- **Parameter Mapping**: Path, query, header, and body parameters are mapped appropriately
+- **Authentication**: OpenAPI security schemes are converted to UTCP auth configurations
+- **Schema Validation**: OpenAPI schemas become UTCP input/output schemas
+
+### Example Conversion
+```yaml
+# OpenAPI Specification
+paths:
+ /users/{id}:
+ get:
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+```
+
+Becomes a UTCP tool:
+```json
+{
+ "name": "get_user",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/users/{id}",
+ "http_method": "GET"
+ },
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "id": {"type": "string"}
+ },
+ "required": ["id"]
+ }
+}
+```
+
+## Response Handling
+
+HTTP responses are processed based on:
+- **Status Codes**: 2xx considered success, 4xx/5xx raise exceptions
+- **Content-Type**:
+ - `application/json`: Parsed as JSON object
+ - Other types: Returned as text string
+- **Error Handling**: HTTP client errors are logged and re-raised
+- **Timeouts**: 10 seconds for tool discovery, 30 seconds for tool execution
+
+## Security Features
+
+### HTTPS Enforcement
+The HTTP protocol enforces secure connections by only allowing:
+- HTTPS URLs (`https://`)
+- Localhost URLs (`http://localhost` or `http://127.0.0.1`)
+
+Any other HTTP URLs will be rejected with a security error to prevent man-in-the-middle attacks.
+
+### OAuth2 Token Caching
+OAuth2 tokens are automatically cached by `client_id` to avoid repeated authentication requests. The protocol supports both:
+- **Body credentials**: Client ID/secret in request body
+- **Header credentials**: Client ID/secret as Basic Auth header
+
+### Request Security
+- URL path parameters are properly URL-encoded to prevent path injection
+- All authentication credentials support environment variable substitution
+- Cookies are supported for API key authentication when required
+
+## Security Considerations
+
+### SSL/TLS Verification
+- Always verify SSL certificates in production
+- Use `verify_ssl: false` only for testing/development
+- Consider certificate pinning for high-security applications
+
+### Authentication Security
+- Store credentials in environment variables, not in configuration files
+- Use OAuth2 for user-facing applications
+- Rotate API keys regularly
+- Implement proper token refresh for OAuth2
+
+### Input Validation
+- Validate all input parameters before substitution
+- Sanitize user inputs to prevent injection attacks
+- Use allowlists for acceptable parameter values
+- Implement rate limiting on the tool provider side
+
+### Network Security
+- HTTPS is enforced by the protocol (except for localhost development)
+- All credentials should use environment variable substitution (e.g., `${API_KEY}`)
+- Path parameters are automatically URL-encoded to prevent injection attacks
+- OAuth2 tokens are cached securely and not logged
+
+## Error Handling
+
+Common HTTP errors and their meanings:
+
+| Status Code | Error Type | Description |
+|-------------|------------|-------------|
+| 400 | Bad Request | Invalid request parameters |
+| 401 | Unauthorized | Authentication required or failed |
+| 403 | Forbidden | Access denied |
+| 404 | Not Found | Resource doesn't exist |
+| 429 | Rate Limited | Too many requests |
+| 500 | Server Error | Internal server error |
+| 503 | Service Unavailable | Service temporarily unavailable |
+
+## Best Practices
+
+### Performance
+- Each request uses a fresh aiohttp ClientSession
+- Tool discovery timeout: 10 seconds
+- Tool execution timeout: 30 seconds
+- OAuth2 tokens are cached to reduce authentication overhead
+
+### Reliability
+- Implement retry logic with exponential backoff
+- Handle network failures gracefully
+- Use circuit breakers for unreliable services
+- Monitor response times and error rates
+
+### Maintainability
+- Use descriptive tool names and descriptions
+- Document all required parameters
+- Provide usage examples
+- Version your APIs and update call templates accordingly
+
+## Complete Examples
+
+### Basic GET Request
+```json
+{
+ "name": "get_user",
+ "call_template_type": "http",
+ "url": "https://api.example.com/users/{user_id}",
+ "http_method": "GET"
+}
+```
+
+### POST with Authentication and Body
+```json
+{
+ "name": "create_user",
+ "call_template_type": "http",
+ "url": "https://api.example.com/users",
+ "http_method": "POST",
+ "content_type": "application/json",
+ "body_field": "user_data",
+ "header_fields": ["request_id"],
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${API_KEY}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+}
+```
+
+### OAuth2 Authentication
+```json
+{
+ "name": "oauth_api",
+ "call_template_type": "http",
+ "url": "https://api.example.com/data",
+ "http_method": "GET",
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "read write"
+ }
+}
+```
+
+## Language-Specific Implementation
+
+For implementation details and examples in your programming language:
+
+- **Python**: See `python-utcp/plugins/communication_protocols/http/`
+- **TypeScript**: [TypeScript HTTP Protocol Documentation](https://github.com/universal-tool-calling-protocol/typescript-utcp/blob/main/docs/protocols/http.md)
+- **Other languages**: Check respective repositories in the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol)
+
+
+
+================================================================================
+FILE: protocols/index.md
+================================================================================
+
+---
+id: protocols
+title: Protocols
+sidebar_position: 4
+---
+
+# Communication Protocol Plugins
+
+UTCP v1.0 features a modular, plugin-based architecture where different communication protocols are implemented as separate plugins. Each protocol plugin provides call templates and communication handlers for specific transport methods.
+
+## Available Protocol Plugins
+
+| Protocol | Plugin Package | Call Template | Use Cases |
+|----------|----------------|---------------|-----------|
+| **[HTTP](./http.md)** | `utcp-http` | `HttpCallTemplate` | REST APIs, webhooks, web services |
+| **[CLI](./cli.md)** | `utcp-cli` | `CliCallTemplate` | Command-line tools, scripts |
+| **[Server-Sent Events](./sse.md)** | `utcp-http` | `SseCallTemplate` | Event streaming, live updates |
+| **[Text Files](./text.md)** | `utcp-text` | `TextCallTemplate` | File reading, static content |
+| **[MCP](./mcp.md)** | `utcp-mcp` | `McpCallTemplate` | Model Context Protocol interop |
+
+## Plugin Architecture
+
+Each protocol plugin consists of:
+
+### Call Templates
+Define how to structure calls for the specific protocol:
+```json
+{
+ "call_template_type": "http",
+ "url": "https://api.example.com/endpoint",
+ "http_method": "POST",
+ "headers": {"Content-Type": "application/json"}
+}
+```
+
+### Communication Protocols
+Handle the actual communication logic for each protocol type. The implementation varies by programming language.
+
+## Installing Protocol Plugins
+
+Protocol plugins are available for different programming languages:
+
+```bash
+# Example installation (Python)
+pip install utcp-http utcp-cli utcp-text utcp-mcp
+
+# Example installation (Node.js)
+npm install @utcp/http @utcp/cli @utcp/text @utcp/mcp
+```
+
+For other languages, check the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol)
+
+## Creating Custom Protocol Plugins
+
+You can extend UTCP with custom communication protocols by implementing the protocol interface in your chosen language. Each implementation must:
+
+1. **Define Call Templates**: Specify the structure for protocol-specific calls
+2. **Implement Communication Handler**: Handle the actual protocol communication
+3. **Register the Protocol**: Make it available to the UTCP client
+
+Example call template structure:
+```json
+{
+ "call_template_type": "custom",
+ "custom_field": "value",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}"
+ }
+}
+```
+
+## Protocol Selection Guide
+
+Choose the right protocol plugin based on your needs:
+
+- **HTTP**: Most common for REST APIs and web services
+- **CLI**: Wrapping existing command-line tools
+- **SSE**: Server-sent events for streaming data
+- **Text**: Reading configuration files or static content
+- **MCP**: Interoperability with Model Context Protocol tools
+
+## Language-Specific Documentation
+
+For implementation details and examples in your programming language:
+
+- **Multi-language**: [UTCP Implementation Examples](https://github.com/universal-tool-calling-protocol) - Examples across Python, TypeScript, Go, and other languages
+- **TypeScript**: [TypeScript UTCP Documentation](https://github.com/universal-tool-calling-protocol/typescript-utcp/tree/main/docs)
+- **Other languages**: Check respective repositories in the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol)
+
+For detailed information about each protocol plugin, see the individual protocol documentation pages.
+
+
+
+================================================================================
+FILE: protocols/mcp.md
+================================================================================
+
+---
+id: mcp
+title: MCP Protocol
+sidebar_position: 6
+---
+
+# MCP Protocol Plugin
+
+The MCP (Model Context Protocol) plugin provides interoperability between UTCP and existing MCP servers, enabling gradual migration from MCP to UTCP while maintaining compatibility with existing MCP tools.
+
+## Call Template Structure
+
+```json
+{
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {
+ "filesystem": {
+ "command": "node",
+ "args": ["mcp-server.js"],
+ "cwd": "/app/mcp",
+ "env": {
+ "NODE_ENV": "production",
+ "LOG_LEVEL": "info"
+ }
+ }
+ }
+ },
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "read:tools"
+ },
+ "register_resources_as_tools": false
+}
+```
+
+## Field Descriptions
+
+For detailed field specifications, examples, and validation rules, see:
+- **[McpCallTemplate API Reference](../api/plugins/communication_protocols/mcp/src/utcp_mcp/mcp_call_template.md)** - Complete field documentation with examples
+- **[McpCommunicationProtocol API Reference](../api/plugins/communication_protocols/mcp/src/utcp_mcp/mcp_communication_protocol.md)** - Implementation details and method documentation
+
+### Key Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `call_template_type` | string | Yes | - | Always "mcp" for MCP providers |
+| `config` | object | Yes | - | Configuration object containing MCP server definitions |
+| `auth` | object | No | null | Optional OAuth2 authentication for HTTP-based MCP servers |
+| `register_resources_as_tools` | boolean | No | false | Whether to register MCP resources as callable tools |
+
+## Server Configuration
+
+### Command-based (stdio) Servers
+```json
+{
+ "config": {
+ "mcpServers": {
+ "my_server": {
+ "command": "python",
+ "args": ["-m", "mcp_server", "--config", "config.json"],
+ "cwd": "/app",
+ "env": {
+ "PYTHONPATH": "/app/lib",
+ "API_KEY": "${MCP_API_KEY}"
+ }
+ }
+ }
+ }
+}
+```
+
+### HTTP-based Servers
+```json
+{
+ "config": {
+ "mcpServers": {
+ "remote_server": {
+ "transport": "http",
+ "url": "https://mcp.example.com/api"
+ }
+ }
+ },
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "mcp:access"
+ }
+}
+```
+
+### Multiple Servers
+```json
+{
+ "config": {
+ "mcpServers": {
+ "filesystem": {
+ "command": "node",
+ "args": ["filesystem-server.js"]
+ },
+ "database": {
+ "command": "python",
+ "args": ["-m", "db_server"]
+ },
+ "remote_api": {
+ "transport": "http",
+ "url": "https://api.example.com/mcp"
+ }
+ }
+ }
+}
+```
+
+## Migration Strategy
+
+The MCP protocol plugin enables a gradual migration path from MCP to native UTCP protocols:
+
+### Phase 1: MCP Integration
+- Use existing MCP servers through UTCP
+- No changes to MCP server code required
+- UTCP client can call MCP tools seamlessly
+
+### Phase 2: Hybrid Approach
+- Some tools use native UTCP protocols
+- Legacy tools continue using MCP
+- Gradual migration of high-value tools
+
+### Phase 3: Full Migration
+- All tools use native UTCP protocols
+- MCP servers deprecated
+- Simplified architecture
+
+## Tool Discovery
+
+The MCP protocol implementation automatically discovers and maps tools:
+
+1. **Session Management**: Creates persistent sessions with MCP servers using MCPClient
+2. **Tool Discovery**: Lists available tools via MCP's `list_tools` method
+3. **Tool Prefixing**: Adds server name prefix (e.g., `filesystem.read_file`) to ensure uniqueness
+4. **Resource Support**: Optionally registers MCP resources as callable tools when `register_resources_as_tools` is true
+5. **Tool Mapping**: Converts MCP tool schema to UTCP tool format automatically
+
+## Request/Response Mapping
+
+### MCP to UTCP Tool Mapping
+```json
+// MCP Tool Definition
+{
+ "name": "read_file",
+ "description": "Read contents of a file",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "path": {"type": "string"}
+ },
+ "required": ["path"]
+ }
+}
+
+// UTCP Tool (after mapping)
+{
+ "name": "filesystem.read_file",
+ "description": "Read contents of a file",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "path": {"type": "string"}
+ },
+ "required": ["path"]
+ },
+ "tool_call_template": {
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {...}
+ }
+ }
+}
+```
+
+### Request Flow
+1. UTCP client receives tool call with server-prefixed name (e.g., `filesystem.read_file`)
+2. MCP plugin extracts server name and tool name
+3. Gets or creates session with target MCP server
+4. Calls MCP server's `call_tool` method
+5. Processes response content (text, JSON, structured output)
+6. Returns mapped result to UTCP client
+
+### Response Processing
+The implementation intelligently processes MCP responses:
+- **Structured output**: Returns `result.structured_output` if available
+- **Text content**: Attempts JSON parsing, number parsing, or returns as string
+- **List content**: Processes each item and returns as list or single item
+- **Error handling**: Session-level errors trigger session restart
+
+## Authentication
+
+### OAuth2 Authentication (HTTP Servers)
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "mcp:read mcp:write"
+ }
+}
+```
+
+### Environment-based Authentication (stdio Servers)
+```json
+{
+ "config": {
+ "mcpServers": {
+ "secure_server": {
+ "command": "secure-mcp-server",
+ "env": {
+ "MCP_AUTH_TOKEN": "${MCP_SERVER_TOKEN}",
+ "MCP_CLIENT_ID": "${MCP_CLIENT_ID}"
+ }
+ }
+ }
+ }
+}
+```
+
+### Security Features
+- **OAuth2 token caching**: Tokens cached by client_id to avoid repeated requests
+- **Session management**: Persistent sessions with automatic error recovery
+- **Environment variables**: Use `${VAR_NAME}` syntax for sensitive credentials
+- **Transport security**: stdio inherits process security, HTTP supports OAuth2
+
+## Error Handling
+
+### Connection Errors
+- Server startup failures
+- Network connectivity issues
+- Authentication failures
+- Timeout errors
+
+### Protocol Errors
+- Invalid MCP messages
+- Unsupported MCP features
+- Tool execution failures
+- Resource access errors
+
+### Error Mapping
+MCP errors are mapped to UTCP exceptions:
+- `InvalidRequest` → `ValidationError`
+- `MethodNotFound` → `ToolNotFoundError`
+- `InternalError` → `ToolCallError`
+
+## Performance Considerations
+
+### Connection Management
+- Persistent connections for stdio transport
+- Connection pooling for HTTP transport
+- Automatic reconnection on failures
+- Graceful shutdown handling
+
+### Request Optimization
+- Batch multiple tool calls when possible
+- Cache tool discovery results
+- Implement request timeouts
+- Monitor response times
+
+## Limitations
+
+### Current Limitations
+- **Prompts**: Not supported in UTCP model
+- **Sampling**: Not applicable to tool calling
+- **Streaming**: MCP streaming calls return single result (no streaming support)
+
+### MCP Feature Support
+Full support for core MCP features:
+- **Tools**: Complete tool discovery and execution support
+- **Resources**: Optional support via `register_resources_as_tools` flag
+- **Authentication**: OAuth2 support for HTTP-based servers
+- **Session management**: Persistent sessions with automatic recovery
+- **Multiple servers**: Single provider can manage multiple MCP servers
+
+### Protocol Mapping
+- **Tool naming**: Server-prefixed names ensure uniqueness across multiple servers
+- **Response processing**: Intelligent parsing of MCP response formats
+- **Error handling**: Session-level vs protocol-level error distinction
+- **Resource tools**: Resources exposed as callable tools when enabled
+
+## Configuration Examples
+
+### Development Setup
+```json
+{
+ "name": "dev_mcp",
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {
+ "filesystem": {
+ "command": "node",
+ "args": ["dev-server.js"],
+ "env": {"NODE_ENV": "development"}
+ },
+ "database": {
+ "command": "python",
+ "args": ["-m", "db_server", "--dev"]
+ }
+ }
+ },
+ "register_resources_as_tools": true
+}
+```
+
+### Production Setup
+```json
+{
+ "name": "prod_mcp",
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {
+ "api_server": {
+ "transport": "http",
+ "url": "https://mcp.example.com/api"
+ }
+ }
+ },
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${MCP_CLIENT_ID}",
+ "client_secret": "${MCP_CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "mcp:access"
+ },
+ "register_resources_as_tools": false
+}
+```
+
+## Best Practices
+
+### Migration Planning
+1. **Inventory** existing MCP servers and tools
+2. **Prioritize** tools for migration based on usage
+3. **Test** MCP integration thoroughly
+4. **Monitor** performance and reliability
+5. **Migrate** incrementally to native UTCP protocols
+
+### Monitoring and Debugging
+- Enable debug logging for MCP communication
+- Monitor server health and response times
+- Track tool usage patterns
+- Log authentication failures
+- Set up alerts for connection issues
+
+### Security
+- Use secure transport methods (HTTPS, WSS)
+- Implement proper authentication
+- Validate all inputs and outputs
+- Monitor for suspicious activity
+- Keep MCP servers updated
+
+## Implementation Notes
+
+The MCP protocol implementation provides:
+
+- **Session persistence**: Reuses MCP sessions for better performance
+- **Automatic recovery**: Handles session failures with automatic retry
+- **Multi-server support**: Single provider manages multiple MCP servers
+- **Resource integration**: Optional resource-to-tool mapping
+- **OAuth2 support**: Full OAuth2 authentication for HTTP servers
+- **Intelligent response processing**: Handles various MCP response formats
+
+### Usage Example
+```python
+import asyncio
+from utcp_client import UtcpClient
+
+async def main():
+ client = UtcpClient()
+
+ # Register MCP provider with multiple servers
+ await client.register_manual(mcp_manual)
+
+ # Call tools with server-prefixed names
+ result = await client.call_tool("filesystem.read_file", {"path": "/data/file.txt"})
+
+ # Access resources as tools (if enabled)
+ resource_data = await client.call_tool("filesystem.resource_config", {})
+
+ await client.close()
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+## Related Protocols
+
+- **[HTTP](./http.md)** - For native HTTP-based tool implementations
+- **[Server-Sent Events (SSE)](./sse.md)** - For real-time streaming tools
+- **TCP/UDP** - For custom protocol implementations
+
+For complete implementation details, see the [MCP Communication Protocol API Reference](../api/plugins/communication_protocols/mcp/src/utcp_mcp/mcp_communication_protocol.md).
+
+
+
+================================================================================
+FILE: protocols/sse.md
+================================================================================
+
+---
+id: sse
+title: Server-Sent Events (SSE)
+sidebar_position: 3
+---
+
+# Server-Sent Events (SSE)
+
+The Server-Sent Events protocol plugin (`utcp-http`) enables UTCP to receive real-time streaming data from HTTP servers. SSE is perfect for tools that need to stream live updates, notifications, or continuous data feeds.
+
+## Installation
+
+SSE support is included with the HTTP plugin:
+
+```bash
+# Example installation (Python)
+pip install utcp-http
+
+# Example installation (Node.js)
+npm install @utcp/http
+```
+
+## Call Template Structure
+
+```json
+{
+ "call_template_type": "sse",
+ "url": "https://api.example.com/events/{stream_id}",
+ "event_type": "data_update",
+ "reconnect": true,
+ "retry_timeout": 30000,
+ "headers": {
+ "X-Custom-Header": "static_value"
+ },
+ "body_field": "payload",
+ "header_fields": ["user_id", "session_token"],
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${API_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+}
+```
+
+## Field Descriptions
+
+For detailed field specifications, examples, and validation rules, see:
+- **[SseCallTemplate API Reference](../api/plugins/communication_protocols/http/src/utcp_http/sse_call_template.md)** - Complete field documentation with examples
+- **[SseCommunicationProtocol API Reference](../api/plugins/communication_protocols/http/src/utcp_http/sse_communication_protocol.md)** - Implementation details and method documentation
+
+### Key Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `call_template_type` | string | Yes | Always "sse" for SSE providers |
+| `url` | string | Yes | SSE endpoint URL with optional path parameters like `{stream_id}` |
+| `event_type` | string | No | Filter for specific event types (default: all events) |
+| `reconnect` | boolean | No | Auto-reconnect on connection loss (default: true) |
+| `retry_timeout` | number | No | Retry timeout in milliseconds (default: 30000) |
+| `headers` | object | No | Static headers for the initial connection |
+| `body_field` | string | No | Tool argument name to map to request body |
+| `header_fields` | array | No | Tool argument names to map to request headers |
+| `auth` | object | No | Authentication configuration |
+
+## Authentication
+
+SSE supports the same authentication methods as HTTP:
+
+### API Key Authentication
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${ACCESS_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+}
+```
+
+Supported locations:
+- `"header"`: API key sent as HTTP header
+- `"query"`: API key sent as query parameter
+- `"cookie"`: API key sent as HTTP cookie
+
+### Basic Authentication
+```json
+{
+ "auth": {
+ "auth_type": "basic",
+ "username": "${USERNAME}",
+ "password": "${PASSWORD}"
+ }
+}
+```
+
+### OAuth2 Authentication
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "read write"
+ }
+}
+```
+
+## Event Handling
+
+### Basic Event Stream
+
+```json
+{
+ "name": "stream_notifications",
+ "description": "Stream real-time notifications",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "user_id": {"type": "string"}
+ },
+ "required": ["user_id"]
+ },
+ "tool_call_template": {
+ "call_template_type": "sse",
+ "url": "https://api.example.com/notifications/stream/{user_id}",
+ "event_type": "notification",
+ "reconnect": true,
+ "retry_timeout": 30000,
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${ACCESS_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+ }
+}
+```
+
+### Filtered Events
+
+```json
+{
+ "call_template_type": "sse",
+ "url": "https://api.example.com/events",
+ "event_type": "order_update",
+ "reconnect": true,
+ "retry_timeout": 15000
+}
+```
+
+## Examples
+
+### Stock Price Stream
+
+```json
+{
+ "name": "stream_stock_prices",
+ "description": "Stream real-time stock price updates",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "symbol": {"type": "string"}
+ },
+ "required": ["symbol"]
+ },
+ "tool_call_template": {
+ "call_template_type": "sse",
+ "url": "https://api.stocks.com/stream/{symbol}",
+ "event_type": "price_update",
+ "reconnect": true,
+ "retry_timeout": 30000,
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${STOCK_API_KEY}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+ }
+}
+```
+
+### Log Monitoring
+
+```json
+{
+ "name": "monitor_logs",
+ "description": "Monitor application logs in real-time",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "service": {"type": "string"},
+ "level": {"type": "string"}
+ },
+ "required": ["service"]
+ },
+ "tool_call_template": {
+ "call_template_type": "sse",
+ "url": "https://logs.example.com/stream/{service}",
+ "event_type": "log_entry",
+ "reconnect": true,
+ "retry_timeout": 45000,
+ "body_field": "filter_config",
+ "header_fields": ["level"],
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${LOG_API_KEY}",
+ "var_name": "X-API-Key",
+ "location": "header"
+ }
+ }
+}
+```
+
+### System Metrics Stream
+
+```json
+{
+ "name": "stream_metrics",
+ "description": "Stream system performance metrics",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "server_id": {"type": "string"},
+ "metrics_config": {"type": "object"}
+ },
+ "required": ["server_id"]
+ },
+ "tool_call_template": {
+ "call_template_type": "sse",
+ "url": "https://monitoring.example.com/metrics/stream/{server_id}",
+ "event_type": "metric_update",
+ "reconnect": true,
+ "retry_timeout": 20000,
+ "body_field": "metrics_config",
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${MONITORING_CLIENT_ID}",
+ "client_secret": "${MONITORING_CLIENT_SECRET}",
+ "token_url": "https://auth.monitoring.com/token",
+ "scope": "metrics:read"
+ }
+ }
+}
+```
+
+## Event Format
+
+SSE events follow the standard format:
+
+```
+event: message
+data: {"type": "update", "value": 123}
+id: event-123
+retry: 3000
+
+event: heartbeat
+data: {"timestamp": "2024-01-15T10:30:00Z"}
+
+data: {"message": "Simple data without event type"}
+```
+
+### Parsed Event Structure
+
+```json
+{
+ "event": "message",
+ "data": {"type": "update", "value": 123},
+ "id": "event-123",
+ "retry": 3000,
+ "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+## Response Handling
+
+### Single Event Response
+
+```json
+{
+ "events": [
+ {
+ "event": "data",
+ "data": {"result": "success"},
+ "id": "1",
+ "timestamp": "2024-01-15T10:30:00Z"
+ }
+ ],
+ "total_events": 1,
+ "duration": 2.5
+}
+```
+
+### Multiple Events Response
+
+```json
+{
+ "events": [
+ {
+ "event": "start",
+ "data": {"status": "processing"},
+ "id": "1"
+ },
+ {
+ "event": "progress",
+ "data": {"percent": 50},
+ "id": "2"
+ },
+ {
+ "event": "complete",
+ "data": {"result": "success"},
+ "id": "3"
+ }
+ ],
+ "total_events": 3,
+ "duration": 15.2
+}
+```
+
+## Error Handling
+
+| Error Type | Description | Handling |
+|------------|-------------|----------|
+| Connection Failed | Cannot connect to SSE endpoint | Raise `SSEConnectionError` |
+| Stream Timeout | No events received within timeout | Return partial results |
+| Parse Error | Invalid SSE event format | Skip malformed events |
+| Authentication Failed | Invalid credentials | Raise `SSEAuthError` |
+| Server Error | HTTP 5xx response | Raise `SSEServerError` |
+
+## Best Practices
+
+1. **Set Appropriate Timeouts**: Configure timeouts based on expected data frequency
+2. **Handle Reconnections**: Enable auto-reconnect for long-running streams
+3. **Filter Events**: Use event filters to reduce unnecessary data processing
+4. **Monitor Performance**: Track event rates and processing times
+5. **Validate Data**: Validate incoming event data against expected schemas
+6. **Handle Backpressure**: Implement buffering for high-frequency events
+7. **Graceful Shutdown**: Properly close streams when done
+
+## Advanced Features
+
+### Dynamic Parameter Substitution
+- **URL path parameters**: Use `{parameter_name}` syntax in URLs
+- **Body field mapping**: Map tool arguments to request body via `body_field`
+- **Header field mapping**: Map tool arguments to headers via `header_fields`
+
+```json
+{
+ "call_template_type": "sse",
+ "url": "https://api.example.com/events/{stream_id}",
+ "event_type": "data_update",
+ "body_field": "filter_config",
+ "header_fields": ["user_context", "session_id"]
+}
+```
+
+### OAuth2 Token Management
+- **Automatic token caching**: Tokens cached by client_id
+- **Token refresh**: Automatic token refresh on expiration
+- **Client credentials flow**: Supports OAuth2 client credentials grant
+
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${OAUTH_CLIENT_ID}",
+ "client_secret": "${OAUTH_CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "stream:read"
+ }
+}
+```
+
+### Multiple Authentication Locations
+- **Header**: Standard Authorization header or custom headers
+- **Query**: API key as URL query parameter
+- **Cookie**: API key sent as HTTP cookie
+
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_TOKEN}",
+ "var_name": "access_token",
+ "location": "cookie"
+ }
+}
+```
+
+## Implementation Notes
+
+The SSE protocol implementation provides:
+
+- **Async streaming**: Real-time event processing with async generators
+- **Automatic reconnection**: Configurable via `reconnect` and `retry_timeout` fields
+- **Event filtering**: Client-side filtering by `event_type`
+- **Authentication caching**: OAuth2 tokens cached by client_id
+- **Security enforcement**: HTTPS or localhost connections only
+- **Error handling**: Graceful handling of connection failures and retries
+
+### Usage Example
+```python
+import asyncio
+from utcp_client import UtcpClient
+
+async def main():
+ client = UtcpClient()
+
+ # Register SSE provider
+ await client.register_manual(sse_manual)
+
+ # Stream events with automatic filtering and reconnection
+ async for event in client.call_tool_streaming("stream_notifications", {"user_id": "123"}):
+ print(f"Event: {event}")
+
+ await client.close()
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+## Common Use Cases
+
+- **Real-time Dashboards**: Live metrics, status updates
+- **Notifications**: User alerts, system notifications
+- **Log Streaming**: Application logs, audit trails
+- **Progress Tracking**: Long-running task progress
+- **Live Data Feeds**: News, social media, sensor data
+- **Chat Applications**: Message streams, typing indicators
+
+## Protocol Comparison
+
+| Feature | SSE | WebSocket | HTTP Polling |
+|---------|-----|-----------|--------------|
+| Server-to-Client | ✅ | ✅ | ✅ |
+| Client-to-Server | ❌ | ✅ | ✅ |
+| Auto-Reconnect | ✅ | Manual | Manual |
+| Overhead | Low | Low | High |
+| Browser Support | ✅ | ✅ | ✅ |
+| Simplicity | High | Medium | High |
+
+## Related Protocols
+
+- **[HTTP](./http.md)** - For standard request/response patterns
+- **WebSocket** - For bidirectional real-time communication
+- **TCP/UDP** - For custom protocol implementations
+
+For complete implementation details, see the [SSE Communication Protocol API Reference](../api/plugins/communication_protocols/http/src/utcp_http/sse_communication_protocol.md).
+
+
+
+================================================================================
+FILE: protocols/streamable-http.md
+================================================================================
+
+---
+id: streamable-http
+title: Streamable HTTP Protocol
+sidebar_position: 2
+---
+
+# Streamable HTTP Protocol
+
+The Streamable HTTP protocol plugin (`utcp-http`) enables UTCP to handle large HTTP responses by streaming them in chunks. This is ideal for tools that return large datasets, files, or progressive results that don't fit into a single response payload. It leverages HTTP Chunked Transfer Encoding.
+
+## Call Template Structure
+
+```json
+{
+ "call_template_type": "streamable_http",
+ "url": "https://api.example.com/download/{file_id}",
+ "http_method": "GET",
+ "content_type": "application/octet-stream",
+ "chunk_size": 4096,
+ "timeout": 60000,
+ "headers": {
+ "Accept": "application/octet-stream"
+ },
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}",
+ "var_name": "Authorization",
+ "location": "header"
+ },
+ "body_field": "request_data",
+ "header_fields": ["custom_header_arg"]
+}
+```
+
+## Field Descriptions
+
+For detailed field specifications, examples, and validation rules, see:
+- **[StreamableHttpCallTemplate API Reference](../api/plugins/communication_protocols/http/src/utcp_http/streamable_http_call_template.md)** - Complete field documentation with examples
+- **[StreamableHttpCommunicationProtocol API Reference](../api/plugins/communication_protocols/http/src/utcp_http/streamable_http_communication_protocol.md)** - Implementation details and method documentation
+
+### Key Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `call_template_type` | string | Yes | - | Always "streamable_http" for streaming HTTP providers |
+| `url` | string | Yes | - | HTTP endpoint URL with optional path parameters like `{file_id}` |
+| `http_method` | string | No | "GET" | HTTP method to use ("GET" or "POST") |
+| `content_type` | string | No | "application/octet-stream" | Content-Type header for requests |
+| `chunk_size` | number | No | 4096 | Size of each data chunk in bytes |
+| `timeout` | number | No | 60000 | Request timeout in milliseconds |
+| `headers` | object | No | null | Static headers to include in requests |
+| `auth` | object | No | null | Authentication configuration |
+| `body_field` | string | No | null | Tool argument name to map to request body |
+| `header_fields` | array | No | null | Tool argument names to map to request headers |
+
+## Response Handling
+
+The protocol processes the incoming stream based on the `Content-Type` header of the response:
+
+- **`application/x-ndjson`**: The stream is parsed as Newline Delimited JSON. Each line is yielded as a separate JSON object.
+- **`application/octet-stream`**: The stream is yielded in binary chunks of the specified `chunk_size`.
+- **`application/json`**: The entire response is buffered and yielded as a single JSON object. This is for endpoints that stream a single, large JSON document.
+- **Other Types**: For any other `Content-Type`, the response is treated as a binary stream and yielded in chunks of `chunk_size`.
+
+## Authentication
+
+Streamable HTTP supports the same authentication methods as HTTP:
+
+### API Key Authentication
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "Bearer ${ACCESS_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+}
+```
+
+Supported locations:
+- `"header"`: API key sent as HTTP header
+- `"query"`: API key sent as query parameter
+- `"cookie"`: API key sent as HTTP cookie
+
+### Basic Authentication
+```json
+{
+ "auth": {
+ "auth_type": "basic",
+ "username": "${USERNAME}",
+ "password": "${PASSWORD}"
+ }
+}
+```
+
+### OAuth2 Authentication
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "read write"
+ }
+}
+```
+
+## Parameter Handling
+
+Streamable HTTP processes tool arguments through a hierarchy:
+
+1. **URL path parameters**: Substituted using `{parameter_name}` syntax
+2. **Body field**: Single argument mapped to request body via `body_field`
+3. **Header fields**: Arguments mapped to headers via `header_fields`
+4. **Query parameters**: Remaining arguments sent as query parameters
+
+### URL Path Parameters
+Parameters in URLs are substituted from tool arguments:
+```json
+{
+ "url": "https://api.example.com/files/{file_id}/download/{format}"
+}
+```
+Tool arguments `file_id` and `format` are substituted into the URL path.
+
+### Variable Substitution
+Authentication and header values support environment variable substitution:
+```json
+{
+ "headers": {
+ "Authorization": "Bearer ${ACCESS_TOKEN}"
+ }
+}
+```
+
+## Security Considerations
+
+### Connection Security
+- **HTTPS enforcement**: Only HTTPS URLs or localhost connections are allowed
+- **Certificate validation**: SSL certificates are validated by default
+- **Secure token handling**: OAuth2 tokens are cached securely
+
+### Authentication Security
+- **Environment variables**: Use `${VAR_NAME}` syntax for sensitive credentials
+- **Token caching**: OAuth2 tokens are cached by client_id to avoid repeated requests
+- **Authentication methods**: Support for API key, Basic auth, and OAuth2
+- **Location flexibility**: API keys can be sent in headers, query params, or cookies
+- **URL encoding**: Path parameters are properly URL-encoded to prevent injection
+
+## Error Handling
+
+Errors are handled similarly to the standard HTTP protocol:
+
+| Status Code | Error Type | Description |
+|---|---|---|
+| 400 | Bad Request | Invalid request parameters or body. |
+| 401 | Unauthorized | Authentication failed or is required. |
+| 403 | Forbidden | The authenticated user does not have permission. |
+| 404 | Not Found | The requested resource or endpoint does not exist. |
+| 5xx | Server Error | An error occurred on the server side. |
+
+Connection errors, timeouts, and other network issues will also be raised as exceptions.
+
+## Usage Examples
+
+### Large File Download
+```json
+{
+ "name": "download_dataset",
+ "description": "Download large dataset files",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "dataset_id": {"type": "string"},
+ "format": {"type": "string", "enum": ["csv", "json", "parquet"]}
+ },
+ "required": ["dataset_id"]
+ },
+ "tool_call_template": {
+ "call_template_type": "streamable_http",
+ "url": "https://data.example.com/datasets/{dataset_id}/download",
+ "http_method": "GET",
+ "chunk_size": 8192,
+ "timeout": 300000,
+ "header_fields": ["format"],
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${DATA_API_KEY}",
+ "var_name": "X-API-Key",
+ "location": "header"
+ }
+ }
+}
+```
+
+### Streaming JSON Data
+```json
+{
+ "name": "export_records",
+ "description": "Export large record sets as streaming NDJSON",
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "table_name": {"type": "string"},
+ "filters": {"type": "object"}
+ },
+ "required": ["table_name"]
+ },
+ "tool_call_template": {
+ "call_template_type": "streamable_http",
+ "url": "https://api.example.com/export/{table_name}",
+ "http_method": "POST",
+ "content_type": "application/json",
+ "chunk_size": 4096,
+ "body_field": "filters",
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${OAUTH_CLIENT_ID}",
+ "client_secret": "${OAUTH_CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "data:export"
+ }
+ }
+}
+```
+
+## Implementation Notes
+
+The Streamable HTTP protocol implementation provides:
+
+- **Chunked streaming**: Processes responses in configurable chunk sizes
+- **Content-type awareness**: Different handling for JSON, NDJSON, and binary content
+- **Authentication caching**: OAuth2 tokens cached by client_id
+- **Security enforcement**: HTTPS or localhost connections only
+- **Error handling**: Graceful handling of connection failures and timeouts
+- **Resource management**: Proper cleanup of HTTP connections and sessions
+
+### Usage Example
+```python
+import asyncio
+from utcp_client import UtcpClient
+
+async def main():
+ client = UtcpClient()
+
+ # Register streamable HTTP provider
+ await client.register_manual(streamable_http_manual)
+
+ # Stream large dataset
+ async for chunk in client.call_tool_streaming("download_dataset", {"dataset_id": "large_dataset_123"}):
+ process_chunk(chunk) # Process each chunk as it arrives
+
+ await client.close()
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+## Related Protocols
+
+- **[HTTP](./http.md)** - For standard request/response interactions
+- **[Server-Sent Events (SSE)](./sse.md)** - For real-time event streams from server to client
+- **TCP/UDP** - For custom protocol implementations
+
+For complete implementation details, see the [Streamable HTTP Communication Protocol API Reference](../api/plugins/communication_protocols/http/src/utcp_http/streamable_http_communication_protocol.md).
+
+
+================================================================================
+FILE: protocols/text.md
+================================================================================
+
+---
+id: text
+title: Text Protocol
+sidebar_position: 5
+---
+
+# Text Protocol
+
+The Text protocol plugin (`utcp-text`) enables UTCP to read UTCP manuals and tool definitions from local JSON/YAML files. This protocol is designed for static tool configurations or environments where manuals are distributed as files.
+
+## Installation
+
+```bash
+# Python installation
+pip install utcp-text
+```
+
+## Call Template Structure
+
+```json
+{
+ "call_template_type": "text",
+ "file_path": "/path/to/manual.json"
+}
+```
+
+## Configuration Options
+
+The Text call template has a simple structure for reading UTCP manuals from files. For complete field specifications and validation rules, see the [Text Call Template API Reference](../api/plugins/communication_protocols/text/src/utcp_text/text_call_template.md).
+
+### Required Fields
+
+- **`call_template_type`**: Must be "text"
+- **`file_path`**: Path to the file containing UTCP manual or tool definitions
+- **`auth`**: Always `None` (text call templates don't support authentication)
+
+## Supported File Types
+
+### UTCP Manual Files
+
+```json
+{
+ "call_template_type": "text",
+ "file_path": "/path/to/utcp_manual.json"
+}
+```
+
+### OpenAPI Specifications
+
+The protocol automatically detects and converts OpenAPI specs to UTCP manuals:
+
+```json
+{
+ "call_template_type": "text",
+ "file_path": "/path/to/openapi.yaml"
+}
+```
+
+### Path Resolution
+
+Relative paths are resolved against the UTCP client's root directory:
+
+```json
+{
+ "call_template_type": "text",
+ "file_path": "manuals/my_tools.json" // Resolved against client root_dir
+}
+```
+
+## Usage Examples
+
+### Manual Registration
+
+#### UTCP Manual File
+
+```json
+{
+ "name": "local_tools_manual",
+ "call_template": {
+ "call_template_type": "text",
+ "file_path": "/path/to/my_tools.json"
+ }
+}
+```
+
+#### OpenAPI Specification
+
+```json
+{
+ "name": "api_tools_manual",
+ "call_template": {
+ "call_template_type": "text",
+ "file_path": "/path/to/openapi.yaml"
+ }
+}
+```
+
+### Tool Execution
+
+When tools are called, the Text protocol returns the content of the configured file:
+
+```json
+{
+ "name": "read_file",
+ "description": "Read content from a file",
+ "inputs": {
+ "type": "object",
+ "properties": {},
+ "required": []
+ },
+ "tool_call_template": {
+ "call_template_type": "text",
+ "file_path": "/path/to/data.txt"
+ }
+}
+```
+
+## Protocol Behavior
+
+### Manual Registration
+
+When registering a manual with `register_manual()`, the protocol:
+
+1. **Reads the file** from the specified `file_path`
+2. **Detects file format** (JSON/YAML)
+3. **Identifies content type**:
+ - UTCP Manual: Validates and returns directly
+ - OpenAPI Spec: Converts to UTCP manual using OpenApiConverter
+4. **Returns result** with loaded tools
+
+### Tool Execution
+
+When calling a tool with `call_tool()`, the protocol:
+
+1. **Reads file content** from the `file_path` in the tool's call template
+2. **Returns raw content** as a string
+
+### Streaming Support
+
+The `call_tool_streaming()` method yields the entire file content as a single chunk.
+
+## File Format Support
+
+### JSON Files
+
+```json
+// /path/to/manual.json
+{
+ "version": "0.2.0",
+ "tools": [
+ {
+ "name": "example_tool",
+ "description": "An example tool",
+ "inputs": {"type": "object", "properties": {}}
+ }
+ ]
+}
+```
+
+### YAML Files
+
+```yaml
+# /path/to/manual.yaml
+version: "0.2.0"
+tools:
+ - name: example_tool
+ description: An example tool
+ inputs:
+ type: object
+ properties: {}
+```
+
+## Error Handling
+
+The Text protocol handles various error conditions:
+
+| Error Type | Condition | Behavior |
+|------------|-----------|----------|
+| File Not Found | File doesn't exist | Returns `RegisterManualResult` with `success: false` |
+| Parse Error | Invalid JSON/YAML | Returns error result with exception details |
+| Validation Error | Invalid UTCP manual | Returns error result with validation details |
+| Generic Error | Unexpected exceptions | Returns error result with traceback |
+
+### Error Response Format
+
+```json
+{
+ "manual_call_template": { /* original template */ },
+ "manual": { "tools": [] },
+ "success": false,
+ "errors": ["Error details here..."]
+}
+```
+
+## Security Considerations
+
+- **Path Resolution**: Relative paths are resolved against the client's `root_dir`
+- **Local Files Only**: Protocol only supports local file system access
+- **No Authentication**: Text call templates don't support auth (always `None`)
+
+## Best Practices
+
+1. **Use Absolute Paths**: When possible, use absolute file paths for clarity
+2. **Validate Files**: Ensure UTCP manual files are valid before registration
+3. **Handle Errors**: Check `RegisterManualResult.success` before using tools
+4. **Organize Manuals**: Keep manual files in a dedicated directory structure
+5. **Version Control**: Include manual files in version control for consistency
+
+## Common Use Cases
+
+- **Static Tool Definitions**: Distributing tool configurations as files
+- **Local Development**: Testing UTCP tools without external dependencies
+- **Offline Environments**: Using tools in environments without network access
+- **Configuration Management**: Reading tool definitions from config files
+- **OpenAPI Integration**: Converting existing OpenAPI specs to UTCP tools
+
+## API Reference
+
+For detailed information about the implementation, see:
+- [Text Call Template API](../api/plugins/communication_protocols/text/src/utcp_text/text_call_template.md)
+- [Text Communication Protocol API](../api/plugins/communication_protocols/text/src/utcp_text/text_communication_protocol.md)
+
+
+
+================================================================================
+FILE: security.md
+================================================================================
+
+---
+id: security
+title: Security Considerations
+sidebar_position: 6
+---
+
+# Security Considerations
+
+Security is critical when enabling direct tool access through UTCP. This guide covers security considerations specific to UTCP's "manual" approach and provides practical guidance for secure implementations.
+
+## UTCP Security Model
+
+### Direct Communication Implications
+
+UTCP's direct communication model has unique security characteristics:
+
+**Advantages:**
+- No middleman to compromise
+- Native security controls remain intact
+- Reduced attack surface (no proxy servers)
+- Existing monitoring and logging continue to work
+
+**Considerations:**
+- Clients must handle multiple authentication methods
+- Manual endpoints become discovery targets
+- Variable substitution introduces injection risks
+
+### Manual Discovery Security
+
+Secure your UTCP manual endpoints:
+
+**Best Practices:**
+- Implement authentication for manual discovery endpoints
+- Validate discovery access tokens
+- Return only tools the client is authorized to see
+- Filter tools based on user permissions
+- Log all manual discovery attempts
+
+## Authentication & Authorization
+
+### Enhanced Authentication Examples
+
+#### API Key with Rotation
+
+```json
+{
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${API_KEY}",
+ "var_name": "X-API-Key",
+ "location": "header"
+ }
+}
+```
+
+**Secure implementation:**
+- Use rotating API keys with current and next key support
+- Implement automatic key rotation based on time
+- Store keys securely in environment variables
+- Validate keys before processing requests
+
+#### OAuth2 with Scope Validation
+
+```json
+{
+ "auth": {
+ "auth_type": "oauth2",
+ "client_id": "${CLIENT_ID}",
+ "client_secret": "${CLIENT_SECRET}",
+ "token_url": "https://auth.example.com/token",
+ "scope": "tools:read tools:execute"
+ }
+}
+```
+
+#### Per-Tool Authorization
+
+```json
+{
+ "name": "admin_tool",
+ "description": "Administrative operations",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/admin/action",
+ "http_method": "POST",
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${ADMIN_TOKEN}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+ }
+}
+```
+
+## Protocol-Specific Security
+
+### HTTP/HTTPS Security
+
+**Required configurations:**
+```json
+{
+ "call_template_type": "http",
+ "url": "https://api.example.com/endpoint",
+ "verify_ssl": true,
+ "timeout": 30,
+ "headers": {
+ "User-Agent": "UTCP-Client/1.0",
+ "X-Request-ID": "${request_id}"
+ }
+}
+```
+
+**Security checklist:**
+- ✅ Always use HTTPS in production
+- ✅ Validate SSL certificates (`verify_ssl: true`)
+- ✅ Set appropriate timeouts
+- ✅ Include request tracking headers
+- ✅ Implement retry limits
+
+### CLI Security
+
+:::danger High Risk Protocol
+CLI execution poses significant security risks. Use with extreme caution.
+:::
+
+**Secure CLI implementation:**
+```json
+{
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "cd /safe/sandbox",
+ "append_to_final_output": false
+ },
+ {
+ "command": "/usr/local/bin/safe-script --input UTCP_ARG_sanitized_input_UTCP_END",
+ "append_to_final_output": true
+ }
+ ],
+ "working_dir": "/safe/sandbox",
+ "env_vars": {
+ "PATH": "/usr/local/bin:/usr/bin",
+ "HOME": "/tmp/sandbox"
+ }
+}
+```
+
+**Security requirements:**
+- ✅ Use absolute paths for commands
+- ✅ Sanitize all input parameters
+- ✅ Run in sandboxed environments
+- ✅ Limit environment variables
+- ✅ Set strict timeouts
+- ✅ Validate exit codes
+- ✅ Use minimal user permissions
+
+**Input sanitization requirements:**
+- Remove dangerous shell metacharacters: `;`, `&`, `|`, `` ` ``, `$`, `()`, `{}`, `[]`, `<>`
+- Escape inputs appropriately for shell execution
+- Use parameterized command execution when possible
+- Validate inputs against expected patterns
+- Implement length limits for all inputs
+
+### Server-Sent Events (SSE) Security
+
+**Secure SSE configuration:**
+```json
+{
+ "call_template_type": "sse",
+ "url": "https://api.example.com/events",
+ "headers": {
+ "Authorization": "Bearer ${SSE_TOKEN}",
+ "Accept": "text/event-stream",
+ "Cache-Control": "no-cache"
+ },
+ "timeout": 300,
+ "max_events": 1000
+}
+```
+
+**Security considerations:**
+- ✅ Authenticate SSE connections
+- ✅ Set maximum event limits
+- ✅ Implement connection timeouts
+- ✅ Validate event data format
+- ✅ Monitor for event flooding
+
+### Text Protocol Security
+
+**Secure file access:**
+```json
+{
+ "call_template_type": "text",
+ "file_path": "/safe/data/${filename}"
+}
+```
+
+**Security measures:**
+- ✅ Restrict file paths to safe directories
+- ✅ Set maximum file size limits
+- ✅ Validate file extensions
+- ✅ Prevent directory traversal attacks
+- ✅ Use safe encoding handling
+
+**Path validation requirements:**
+- Resolve all paths to absolute paths
+- Check if paths are within allowed directories
+- Handle symbolic links by resolving them first
+- Validate against directory traversal attacks (`../`)
+- Return false for any path resolution errors
+- Use allowlists of permitted directories
+
+### MCP Security
+
+**Secure MCP server configuration:**
+```json
+{
+ "call_template_type": "mcp",
+ "config": {
+ "mcpServers": {
+ "server_name": {
+ "transport": "stdio",
+ "command": ["python", "-m", "my_mcp_server"]
+ }
+ }
+ }
+}
+```
+
+**Security considerations:**
+- ✅ Use trusted MCP server implementations
+- ✅ Sandbox MCP server processes
+- ✅ Limit server resource usage
+- ✅ Monitor server health and logs
+- ✅ Implement server restart policies
+
+## Input Validation & Sanitization
+
+### JSON Schema Validation
+
+**Comprehensive input validation:**
+```json
+{
+ "inputs": {
+ "type": "object",
+ "properties": {
+ "email": {
+ "type": "string",
+ "format": "email",
+ "maxLength": 254
+ },
+ "age": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 150
+ },
+ "tags": {
+ "type": "array",
+ "items": {"type": "string", "pattern": "^[a-zA-Z0-9_-]+$"},
+ "maxItems": 10
+ }
+ },
+ "required": ["email"],
+ "additionalProperties": false
+ }
+}
+```
+
+### Parameter Sanitization
+
+**Server-side validation requirements:**
+- Use regex patterns to validate input formats (e.g., `^[a-zA-Z0-9_-]+$` for user IDs)
+- Implement maximum length limits for all string inputs
+- Remove dangerous characters like `<>`, `"`, `'` from user inputs
+- Validate all inputs against expected schemas
+- Sanitize inputs before processing
+
+## Secure Variable Handling
+
+### Environment Variable Security
+
+**Secure variable loading requirements:**
+- Only allow variables with approved prefixes (e.g., `UTCP_`, `API_`)
+- Validate variable names against allowlists
+- Implement length limits for variable values (e.g., max 10,000 characters)
+- Check for dangerous characters in values (`<`, `>`, `"`, `'`)
+- Use secure variable substitution methods
+- Log all variable access attempts
+
+### Runtime Variable Substitution
+
+**Secure substitution requirements:**
+
+Implement variable substitution with these security measures:
+- Only substitute variables matching the pattern `${variable_name}`
+- Validate variable names contain only alphanumeric characters and underscores
+- Check that all variables exist before substitution
+- Sanitize variable values to prevent injection attacks
+- Reject values containing dangerous characters like `<`, `>`, `"`, `'`, `;`, `&`
+- Limit variable value length to prevent buffer overflow attacks
+
+## Network & Transport Security
+
+### TLS Configuration
+
+**Minimum TLS requirements:**
+**TLS configuration requirements:**
+
+Configure secure HTTP clients with these settings:
+- Enable SSL certificate verification
+- Set reasonable connection timeouts (e.g., 30 seconds)
+- Limit maximum connections to prevent resource exhaustion
+- Use TLS 1.2 or higher as minimum version
+- Enable hostname verification
+- Require certificate verification (CERT_REQUIRED mode)
+
+### Certificate Validation
+
+**Enhanced certificate validation:**
+
+Implement robust certificate validation:
+- Use trusted certificate authority bundles
+- Enable hostname verification against certificate
+- Require valid certificate chains
+- Set minimum TLS version to 1.2
+- Configure strong cipher suites (ECDHE+AESGCM, CHACHA20, DHE+AESGCM)
+- Reject weak algorithms (aNULL, MD5, DSS)
+
+## Monitoring & Incident Response
+
+### Security Logging
+
+**Comprehensive security logging:**
+
+Implement security logging with these components:
+- **Tool Call Logging**: Record all tool invocations with user ID, tool name, timestamp, success status, and parameters
+- **Authentication Logging**: Log authentication attempts, failures, and reasons
+- **Structured Format**: Use JSON format for easy parsing and analysis
+- **Sensitive Data Protection**: Avoid logging sensitive information like passwords or tokens
+- **Audit Trail**: Maintain immutable logs for compliance and forensic analysis
+
+### Anomaly Detection
+
+**Basic anomaly detection:**
+
+Implement anomaly detection with these features:
+- **Rate Limiting**: Track requests per user with configurable limits (e.g., 60 calls/minute, 1000 calls/hour)
+- **Time Window Management**: Clean old entries and maintain sliding time windows
+- **Multi-tier Limits**: Enforce both short-term (per minute) and long-term (per hour) rate limits
+- **Automatic Blocking**: Reject requests that exceed configured thresholds
+- **Call Tracking**: Record timestamps of all user requests for analysis
+
+## Security Testing & Validation
+
+### Testing Methodologies
+
+**Security test examples:**
+
+Implement comprehensive security testing:
+- **Injection Prevention Tests**: Test for SQL injection, command injection, and other malicious inputs
+- **Path Traversal Tests**: Verify protection against directory traversal attacks (../../../etc/passwd)
+- **Rate Limiting Tests**: Confirm rate limiting enforcement under high load
+- **Authentication Tests**: Validate proper authentication and authorization
+- **Input Validation Tests**: Test boundary conditions and malformed inputs
+
+### Security Automation
+
+**Automated security checks:**
+
+Implement automated security validation:
+- **Protocol Security**: Verify HTTPS usage instead of HTTP for web requests
+- **Credential Detection**: Check for hardcoded passwords, secrets, or API keys
+- **Variable Validation**: Ensure proper variable substitution patterns ($\{variable\})
+- **CLI Security**: Validate command-line tools use absolute paths and safe commands
+- **URL Validation**: Check for suspicious or malformed URLs
+- **Configuration Review**: Automated scanning of UTCP manuals for security issues
+
+## Security Checklist
+
+### Tool Provider Security
+
+- [ ] UTCP manual endpoint requires authentication
+- [ ] All tool endpoints use HTTPS/WSS
+- [ ] Input validation implemented for all tools
+- [ ] Rate limiting configured per user/tool
+- [ ] Security logging enabled
+- [ ] Credentials stored securely (not hardcoded)
+- [ ] SSL certificate validation enabled
+- [ ] Appropriate timeouts configured
+- [ ] Error messages don't leak sensitive information
+
+### Tool Consumer Security
+
+- [ ] Variable substitution is sanitized
+- [ ] SSL certificate verification enabled
+- [ ] Connection timeouts configured
+- [ ] Rate limiting respected
+- [ ] Security events logged
+- [ ] Credentials rotated regularly
+- [ ] Network connections monitored
+- [ ] Input validation before tool calls
+
+### Protocol-Specific Security
+
+- [ ] **HTTP**: HTTPS only, certificate validation
+- [ ] **CLI**: Sandboxed execution, input sanitization
+- [ ] **SSE**: Authenticated connections, event limits
+- [ ] **Text**: Path validation, size limits
+- [ ] **MCP**: Trusted servers, resource limits
+
+By following these security guidelines, you can safely implement UTCP while maintaining strong security posture across all communication protocols.
+
+For protocol-specific security details, see:
+- [HTTP Security](./protocols/http.md#security-considerations)
+- [CLI Security](./protocols/cli.md#security-considerations)
+- [SSE Security](./protocols/sse.md#security-considerations)
+- [Text Security](./protocols/text.md#security-considerations)
+- [MCP Security](./protocols/mcp.md#security-considerations)
+
+
+
+================================================================================
+FILE: utcp-vs-mcp.md
+================================================================================
+
+---
+id: utcp-vs-mcp
+title: UTCP vs MCP
+sidebar_position: 5
+---
+
+# UTCP vs MCP: A Comprehensive Comparison
+
+:::info Language Examples
+This comparison uses **Python** examples. Both UTCP and MCP have implementations in multiple languages - check respective GitHub organizations for language-specific examples.
+:::
+
+This guide compares the Universal Tool Calling Protocol (UTCP) with the Model Context Protocol (MCP), helping you choose the right approach for your AI tool integration needs.
+
+## Video Overview
+
+
+
+## Quick Comparison
+
+| Aspect | UTCP | MCP |
+|--------|------|-----|
+| **Philosophy** | Manual (describes how to call tools) | Middleman (wraps tools in protocol) |
+| **Architecture** | Agent → Tool (Direct) | Agent → MCP Server → Tool |
+| **Infrastructure** | None required | Wrapper servers needed |
+| **Protocols** | HTTP, WebSocket, CLI, SSE, etc. | JSON-RPC over stdio/HTTP |
+| **Performance** | Native tool performance | Additional proxy overhead |
+| **Maintenance** | Minimal | High (server maintenance) |
+
+## Architectural Differences
+
+### UTCP: The "Manual" Approach
+
+UTCP provides a standardized way to describe how to call existing tools directly:
+
+```json
+{
+ "manual_version": "1.0.0",
+ "utcp_version": "1.0.1",
+ "tools": [{
+ "name": "get_weather",
+ "description": "Get current weather",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.weather.com/current",
+ "http_method": "GET",
+ "query_params": {"location": "${location}"}
+ }
+ }]
+}
+```
+
+**Flow:** Agent discovers manual → Agent calls tool directly
+
+### MCP: The "Middleman" Approach
+
+MCP requires building servers that wrap your tools:
+
+**MCP Server Implementation Requirements:**
+- Create a dedicated server process for each tool provider
+- Implement tool listing functionality to expose available tools
+- Implement tool calling handlers that proxy requests to actual APIs
+- Maintain server infrastructure and handle client connections
+- Route all tool calls through the MCP server layer
+
+**Flow:** Agent → MCP Server → Tool → MCP Server → Agent
+
+## Technical Comparison
+
+### Performance Impact
+
+#### UTCP Performance
+
+**Direct API calls with no overhead:**
+- Make HTTP requests directly to weather service endpoints
+- No intermediate proxy servers or additional network hops
+- Latency equals API response time only (~100ms)
+- Native HTTP client performance with connection pooling
+
+#### MCP Performance
+
+**Requires MCP server proxy:**
+- Connect to MCP server before making tool calls
+- Route requests through MCP server to actual weather API
+- Additional network hop adds latency overhead
+- Latency includes API response time plus MCP server processing (~150ms)
+
+### Infrastructure Requirements
+
+#### UTCP Infrastructure
+
+**Minimal infrastructure requirements:**
+- Add single discovery endpoint to existing API (e.g., GET /utcp)
+- Return static JSON manual describing available tools
+- No additional servers, processes, or infrastructure needed
+- Total infrastructure: 0 additional servers
+
+#### MCP Infrastructure
+
+**MCP infrastructure requirements:**
+- Requires dedicated MCP server processes for each tool provider
+- Process management, monitoring, and scaling infrastructure needed
+- Client connection management and session handling required
+- Total infrastructure: N MCP servers (one per tool provider)
+
+### Protocol Support Comparison
+
+#### UTCP Protocol Flexibility
+```json
+{
+ "tools": [
+ {
+ "name": "http_tool",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.example.com/data"
+ }
+ },
+ {
+ "name": "websocket_tool",
+ "tool_call_template": {
+ "call_template_type": "websocket",
+ "url": "wss://api.example.com/ws"
+ }
+ },
+ {
+ "name": "cli_tool",
+ "tool_call_template": {
+ "call_template_type": "cli",
+ "commands": [
+ {
+ "command": "git status --porcelain",
+ "append_to_final_output": true
+ }
+ ]
+ }
+ }
+ ]
+}
+```
+
+#### MCP Protocol Limitation
+
+**MCP protocol constraints:**
+- Only supports JSON-RPC over stdio/HTTP transport
+- All tools must be wrapped in MCP server implementations
+- Cannot directly call WebSocket, CLI, or other native protocols
+- Requires protocol translation layer for non-HTTP tools
+
+## Feature Comparison
+
+### Authentication & Security
+
+#### UTCP: Native Authentication
+```json
+{
+ "tool_call_template": {
+ "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"
+ }
+ }
+}
+```
+
+**Benefits:**
+- Uses existing authentication systems
+- No credential translation needed
+- Native rate limiting and monitoring
+- Existing security policies apply
+
+#### MCP: Server-Mediated Authentication
+
+**MCP server authentication requirements:**
+- MCP server must handle authentication translation between client and API
+- Server stores and manages API credentials on behalf of clients
+- Server makes authenticated calls to actual APIs using stored credentials
+- Requires credential management and secure storage in MCP server
+
+**Challenges:**
+- Credential management in MCP servers
+- Additional security layer to maintain
+- Auth translation complexity
+
+### Streaming & Real-time Data
+
+#### UTCP: Native Streaming Support
+```json
+{
+ "name": "stream_logs",
+ "tool_call_template": {
+ "call_template_type": "sse",
+ "url": "https://api.example.com/logs/stream",
+ "timeout": 300
+ }
+}
+```
+
+#### MCP: Limited Streaming
+
+**MCP streaming limitations:**
+- MCP has basic streaming capabilities but requires server implementation
+- More complex to set up and maintain than native streaming protocols
+- Additional abstraction layer between client and streaming data source
+
+### Error Handling
+
+#### UTCP: Native Error Responses
+
+**Direct error handling:**
+- Errors come directly from the tool without translation
+- Native HTTP status codes and error messages preserved
+- Full error context available including headers and response body
+- No error translation or abstraction layer
+
+#### MCP: Wrapped Error Responses
+
+**Error abstraction layer:**
+- Errors are wrapped and translated by MCP server
+- Original error context may be lost in translation
+- MCP-specific error format instead of native tool errors
+- Additional debugging complexity due to error wrapping
+
+## Migration & Interoperability
+
+### Migrating from MCP to UTCP
+
+UTCP provides an MCP plugin for gradual migration:
+
+**Migration Strategy:**
+- **Phase 1**: Use existing MCP servers via UTCP's MCP protocol plugin
+- Configure UTCP client to connect to legacy MCP servers using MCP call templates
+- **Phase 2**: Migrate high-value tools to native UTCP protocols (HTTP, WebSocket, CLI)
+- **Phase 3**: Deprecate MCP servers once migration is complete
+
+[**Complete migration guide →**](./protocols/mcp.md)
+
+### Hybrid Approach
+
+You can use both protocols simultaneously:
+
+**Hybrid approach during migration:**
+- Configure UTCP client with both native UTCP and legacy MCP call templates
+- Native UTCP tools use direct HTTP/WebSocket/CLI protocols
+- Legacy MCP tools continue using MCP protocol plugin
+- Gradually migrate tools from MCP to native UTCP protocols
+- Single client interface for both native and legacy tools
+
+## Enterprise Decision Factors
+
+### Total Cost of Ownership
+
+#### UTCP TCO
+```
+Infrastructure: $0 (uses existing APIs)
+Development: Low (add one endpoint)
+Maintenance: Minimal (static JSON)
+Scaling: Automatic (scales with existing API)
+Monitoring: Existing tools work
+```
+
+#### MCP TCO
+```
+Infrastructure: High (dedicated servers)
+Development: High (build wrapper servers)
+Maintenance: High (server management)
+Scaling: Complex (scale MCP servers separately)
+Monitoring: Additional monitoring stack needed
+```
+
+### Development Velocity
+
+#### UTCP Development Speed
+
+**Rapid deployment timeline:**
+- **Day 1**: Add UTCP discovery endpoint to existing API
+- **Day 2**: Tools are immediately available to AI agents
+- No additional infrastructure, servers, or deployment needed
+- Minimal code changes to existing systems
+
+#### MCP Development Speed
+
+**Extended development timeline:**
+- **Week 1-2**: Build dedicated MCP server implementation
+- **Week 3**: Deploy and configure server infrastructure
+- **Week 4**: Set up monitoring, logging, and scaling
+- **Week 5**: Handle production issues and debugging
+- **Ongoing**: Server maintenance, updates, and operations
+
+### Risk Assessment
+
+| Risk Factor | UTCP | MCP |
+|-------------|------|-----|
+| **Single Point of Failure** | None (direct calls) | MCP servers |
+| **Vendor Lock-in** | Low (standard protocols) | Medium (MCP-specific) |
+| **Maintenance Burden** | Low | High |
+| **Security Surface** | Minimal | Expanded |
+| **Performance Risk** | Low | Medium |
+
+## Decision Framework
+
+### Choose UTCP When:
+
+✅ **You have existing APIs** that work well
+✅ **You want minimal infrastructure** overhead
+✅ **You need multiple protocols** (HTTP, WebSocket, CLI, etc.)
+✅ **You prioritize performance** and direct communication
+✅ **You want to leverage existing** auth, monitoring, scaling
+✅ **You have limited resources** for server maintenance
+✅ **You need rapid deployment** of AI tool access
+
+### Choose MCP When:
+
+✅ **You need strict protocol standardization** across all tools
+✅ **You're building a closed ecosystem** with full control
+✅ **You have resources** for building and maintaining servers
+✅ **You need MCP-specific features** like resources and prompts
+✅ **You're already invested** in MCP infrastructure
+✅ **You prefer centralized control** over tool access
+
+### Hybrid Approach When:
+
+✅ **You're migrating from MCP** to UTCP gradually
+✅ **You have mixed requirements** (some tools need MCP features)
+✅ **You want to evaluate both** approaches in production
+✅ **You have legacy MCP investments** to preserve
+
+## Real-World Examples
+
+### E-commerce API Integration
+
+#### UTCP Approach
+
+**E-commerce API with UTCP:**
+- Keep existing product API endpoints unchanged (GET /products/\{product_id\})
+- Add single UTCP discovery endpoint (GET /utcp)
+- Return UTCP manual describing available tools and how to call them
+- Tools directly reference existing API endpoints with proper parameters
+- Total additional code: ~10 lines
+- Additional infrastructure: 0 servers
+
+#### MCP Approach
+
+**E-commerce API with MCP:**
+- Requires building dedicated MCP server wrapper
+- Implement tool listing and calling handlers in MCP server
+- MCP server calls existing API endpoints on behalf of clients
+- Additional server deployment, monitoring, and scaling required
+- Total additional code: ~50+ lines
+- Additional infrastructure: 1+ servers
+
+### Database Query Tool
+
+#### UTCP Approach
+```json
+{
+ "name": "query_database",
+ "tool_call_template": {
+ "call_template_type": "http",
+ "url": "https://api.company.com/query",
+ "http_method": "POST",
+ "body": {"sql": "${query}"},
+ "auth": {
+ "auth_type": "api_key",
+ "api_key": "${DB_API_KEY}",
+ "var_name": "Authorization",
+ "location": "header"
+ }
+ }
+}
+```
+
+#### MCP Approach
+**MCP database approach:**
+- Requires MCP server with database connection management
+- Connection pooling, query validation, and security in MCP server
+- Much more complex implementation than direct database access
+- Additional abstraction layer between client and database
+
+## Performance Benchmarks
+
+### Latency Comparison
+
+| Scenario | UTCP | MCP | Difference |
+|----------|------|-----|------------|
+| Simple API call | 50ms | 75ms | +50% overhead |
+| Complex query | 200ms | 250ms | +25% overhead |
+| File operation | 10ms | 20ms | +100% overhead |
+| Streaming data | Real-time | Buffered | Significant delay |
+
+### Resource Usage
+
+| Resource | UTCP | MCP |
+|----------|------|-----|
+| Memory | 0MB (no servers) | 50-200MB per server |
+| CPU | 0% (no processing) | 5-15% per server |
+| Network | Direct | Double hops |
+| Storage | 0GB | Logs, state, config |
+
+## Migration Timeline
+
+### From MCP to UTCP
+
+**Phase 1 (Week 1): Assessment**
+- Inventory existing MCP servers
+- Identify high-value tools for migration
+- Plan migration strategy
+
+**Phase 2 (Week 2-3): Hybrid Setup**
+- Install UTCP with MCP plugin
+- Test existing MCP tools through UTCP
+- Validate functionality
+
+**Phase 3 (Week 4-8): Gradual Migration**
+- Migrate tools one by one to native UTCP
+- Add `/utcp` endpoints to existing APIs
+- Update client configurations
+
+**Phase 4 (Week 9+): Cleanup**
+- Deprecate MCP servers
+- Remove MCP infrastructure
+- Monitor and optimize
+
+[**Detailed migration guide →**](./migration-v0.1-to-v1.0.md)
+
+## Community & Ecosystem
+
+### UTCP Ecosystem
+- **Multiple language implementations**: Python, TypeScript, Go, Rust
+- **Growing protocol support**: HTTP, WebSocket, CLI, SSE, Text, MCP
+- **Active development**: Regular releases and improvements
+- **Open governance**: RFC process for changes
+
+### MCP Ecosystem
+- **Anthropic-led development**: Centralized development
+- **Growing tool library**: Community-contributed servers
+- **IDE integrations**: Claude Desktop, Cline, etc.
+- **Established patterns**: Well-documented server patterns
+
+## Conclusion
+
+Both UTCP and MCP solve the tool integration problem, but with fundamentally different approaches:
+
+**UTCP excels when you:**
+- Want to leverage existing APIs without additional infrastructure
+- Need support for multiple communication protocols
+- Prioritize performance and direct communication
+- Have limited resources for server maintenance
+- Want rapid deployment and minimal complexity
+
+**MCP excels when you:**
+- Need strict protocol standardization
+- Are building a controlled ecosystem
+- Have resources for server infrastructure
+- Need MCP-specific features beyond tool calling
+- Prefer centralized tool management
+
+**For most organizations**, UTCP's "manual" approach offers significant advantages in terms of simplicity, performance, and cost-effectiveness. The ability to expose existing APIs to AI agents with minimal changes and no additional infrastructure makes it an attractive choice for rapid AI tool integration.
+
+**For gradual adoption**, consider starting with UTCP's MCP plugin to use existing MCP servers while migrating high-value tools to native UTCP protocols over time.
+
+## Next Steps
+
+### To Get Started with UTCP:
+1. **[Read the implementation guide](./implementation.md)** - Learn how to implement UTCP
+2. **[Choose your protocols](./protocols/index.md)** - Select communication methods
+3. **[Check examples](https://github.com/universal-tool-calling-protocol)** - See real implementations across multiple languages
+
+### To Migrate from MCP:
+1. **[Read the MCP integration guide](./protocols/mcp.md)** - Use MCP tools via UTCP
+2. **[Plan your migration](./migration-v0.1-to-v1.0.md)** - Step-by-step migration process
+3. **[Join the community](https://discord.gg/ZpMbQ8jRbD)** - Get migration support
+
+### To Learn More:
+- **[UTCP Architecture](./api/index.md)** - Technical deep dive
+- **[Security Considerations](./security.md)** - Security best practices
+- **[Tool Provider Guide](./for-tool-providers.md)** - Expose your tools
+
+
+
+================================================================================
+END OF DOCUMENTATION
+================================================================================
\ No newline at end of file