universal-tool-calling-protocol
diff --git a/‎CLAUDE.md‎
Lines changed: 113 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 113 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 1 addition & 0 deletions b/‎README.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎example/src/websocket_example/README.md‎
Lines changed: 87 additions & 0 deletions b/‎example/src/websocket_example/README.md‎
Lines changed: 87 additions & 0 deletions
diff --git a/‎example/src/websocket_example/providers.json‎
Lines changed: 11 additions & 0 deletions b/‎example/src/websocket_example/providers.json‎
Lines changed: 11 additions & 0 deletions
@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the Python implementation of the Universal Tool Calling Protocol (UTCP), a flexible and scalable standard for defining and interacting with tools across various communication protocols. UTCP emphasizes scalability, interoperability, and ease of use compared to other protocols like MCP.
+
+## Development Commands
+
+### Building and Installation
+```bash
+# Create virtual environment and install dependencies
+conda create --name utcp python=3.10
+conda activate utcp
+pip install -r requirements.txt
+python -m pip install --upgrade pip
+
+# Build the package
+python -m build
+
+# Install locally
+pip install dist/utcp-<version>.tar.gz
+```
+
+### Testing
+```bash
+# Run all tests
+pytest
+
+# Run tests with coverage
+pytest --cov=src/utcp
+
+# Run specific plugin tests
+pytest plugins/communication_protocols/http/tests/
+pytest plugins/communication_protocols/websocket/tests/
+```
+
+### Development Dependencies
+- Install dev dependencies: `pip install -e .[dev]`
+- Key dev tools: pytest, pytest-asyncio, pytest-aiohttp, pytest-cov, coverage, fastapi, uvicorn
+
+## Architecture Overview
+
+### Core Components
+
+**Client Architecture (`src/utcp/client/`)**:
+- `UtcpClient`: Main entry point for UTCP ecosystem interaction
+- `UtcpClientConfig`: Pydantic model for client configuration
+- `ClientTransportInterface`: Abstract base for transport implementations
+- `ToolRepository`: Interface for storing/retrieving tools (default: `InMemToolRepository`)
+- `ToolSearchStrategy`: Interface for tool search algorithms (default: `TagSearchStrategy`)
+
+**Shared Models (`src/utcp/shared/`)**:
+- `Tool`: Core tool definition with inputs/outputs schemas
+- `Provider`: Defines communication protocols for tools
+- `UtcpManual`: Contains discovery information for tool collections
+- `Auth`: Authentication models (API key, Basic, OAuth2)
+
+**Transport Layer (`src/utcp/client/transport_interfaces/`)**:
+Each transport handles protocol-specific communication:
+- `HttpClientTransport`: RESTful HTTP/HTTPS APIs
+- `CliTransport`: Command Line Interface tools
+- `SSEClientTransport`: Server-Sent Events
+- `StreamableHttpClientTransport`: HTTP chunked transfer
+- `MCPTransport`: Model Context Protocol interoperability
+- `TextTransport`: Local file-based tool definitions
+- `GraphQLClientTransport`: GraphQL APIs
+
+### Key Design Patterns
+
+**Provider Registration**: Tools are discovered via `UtcpManual` objects from providers, then registered in the client's `ToolRepository`.
+
+**Namespaced Tool Calling**: Tools are called using format `provider_name.tool_name` to avoid naming conflicts.
+
+**OpenAPI Auto-conversion**: HTTP providers can point to OpenAPI v3 specs for automatic tool generation.
+
+**Extensible Authentication**: Support for API keys, Basic auth, and OAuth2 with per-provider configuration.
+
+## Configuration
+
+### Provider Configuration
+Tools are configured via `providers.json` files that specify:
+- Provider name and type
+- Connection details (URL, method, etc.)
+- Authentication configuration
+- Tool discovery endpoints
+
+### Client Initialization
+```python
+client = await UtcpClient.create(
+    config={
+        "providers_file_path": "./providers.json",
+        "load_variables_from": [{"type": "dotenv", "env_file_path": ".env"}]
+    }
+)
+```
+
+## File Structure
+
+- `src/utcp/client/`: Client implementation and transport interfaces
+- `src/utcp/shared/`: Shared models and utilities
+- `tests/`: Comprehensive test suite with transport-specific tests
+- `example/`: Complete usage examples including LLM integration
+- `scripts/`: Utility scripts for OpenAPI conversion and API fetching
+
+## Important Implementation Notes
+
+- All async operations use `asyncio`
+- Pydantic models throughout for validation and serialization
+- Transport interfaces are protocol-agnostic and swappable
+- Tool search supports tag-based ranking and keyword matching
+- Variable substitution in configuration supports environment variables and .env files
@@ -86,6 +86,7 @@ UTCP supports multiple communication protocols through dedicated plugins:
 | [`utcp-cli`](plugins/communication_protocols/cli/) | Command-line tools | ✅ Stable | [CLI Plugin README](plugins/communication_protocols/cli/README.md) |
 | [`utcp-mcp`](plugins/communication_protocols/mcp/) | Model Context Protocol | ✅ Stable | [MCP Plugin README](plugins/communication_protocols/mcp/README.md) |
 | [`utcp-text`](plugins/communication_protocols/text/) | Local file-based tools | ✅ Stable | [Text Plugin README](plugins/communication_protocols/text/README.md) |
+| [`utcp-websocket`](plugins/communication_protocols/websocket/) | WebSocket real-time bidirectional communication | ✅ Stable | [WebSocket Plugin README](plugins/communication_protocols/websocket/README.md) |
 | [`utcp-socket`](plugins/communication_protocols/socket/) | TCP/UDP protocols | 🚧 In Progress | [Socket Plugin README](plugins/communication_protocols/socket/README.md) |
 | [`utcp-gql`](plugins/communication_protocols/gql/) | GraphQL APIs | 🚧 In Progress | [GraphQL Plugin README](plugins/communication_protocols/gql/README.md) |
 
 
@@ -0,0 +1,87 @@
+# WebSocket Transport Example
+
+This example demonstrates how to use the UTCP WebSocket transport for real-time communication.
+
+## Overview
+
+The WebSocket transport provides:
+- Real-time bidirectional communication
+- Tool discovery via WebSocket handshake
+- Streaming tool execution
+- Authentication support (API Key, Basic Auth, OAuth2)
+- Automatic reconnection and keep-alive
+
+## Files
+
+- `websocket_server.py` - Mock WebSocket server implementing UTCP protocol
+- `websocket_client.py` - Client example using WebSocket transport
+- `providers.json` - WebSocket provider configuration
+
+## Protocol
+
+The UTCP WebSocket protocol uses JSON messages:
+
+### Tool Discovery
+```json
+// Client sends:
+{"type": "discover", "request_id": "unique_id"}
+
+// Server responds:
+{
+  "type": "discovery_response", 
+  "request_id": "unique_id",
+  "tools": [...]
+}
+```
+
+### Tool Execution
+```json
+// Client sends:
+{
+  "type": "call_tool",
+  "request_id": "unique_id", 
+  "tool_name": "tool_name",
+  "arguments": {...}
+}
+
+// Server responds:
+{
+  "type": "tool_response",
+  "request_id": "unique_id",
+  "result": {...}
+}
+```
+
+## Running the Example
+
+1. Start the mock WebSocket server:
+```bash
+python websocket_server.py
+```
+
+2. In another terminal, run the client:
+```bash
+python websocket_client.py
+```
+
+## Configuration
+
+The `providers.json` shows how to configure WebSocket providers with authentication:
+
+```json
+[
+  {
+    "name": "websocket_tools",
+    "provider_type": "websocket",
+    "url": "ws://localhost:8765/ws",
+    "auth": {
+      "auth_type": "api_key",
+      "api_key": "your-api-key",
+      "var_name": "X-API-Key",
+      "location": "header"
+    },
+    "keep_alive": true,
+    "protocol": "utcp-v1"
+  }
+]
+```
@@ -0,0 +1,11 @@
+[
+  {
+    "name": "websocket_tools",
+    "provider_type": "websocket",
+    "url": "ws://localhost:8765/ws",
+    "keep_alive": true,
+    "headers": {
+      "User-Agent": "UTCP-WebSocket-Client/1.0"
+    }
+  }
+]