Skip to content

Commit 03a4b9f

Browse files
h3xxith3xxit
authored
Merge pull request #70 from universal-tool-calling-protocol/dev
 Add WebSocket transport implementation for real-time communication …
2 parents 74a11e2 + 81cab59 commit 03a4b9f

15 files changed

Lines changed: 2587 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
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.
8+
9+
## Development Commands
10+
11+
### Building and Installation
12+
```bash
13+
# Create virtual environment and install dependencies
14+
conda create --name utcp python=3.10
15+
conda activate utcp
16+
pip install -r requirements.txt
17+
python -m pip install --upgrade pip
18+
19+
# Build the package
20+
python -m build
21+
22+
# Install locally
23+
pip install dist/utcp-<version>.tar.gz
24+
```
25+
26+
### Testing
27+
```bash
28+
# Run all tests
29+
pytest
30+
31+
# Run tests with coverage
32+
pytest --cov=src/utcp
33+
34+
# Run specific plugin tests
35+
pytest plugins/communication_protocols/http/tests/
36+
pytest plugins/communication_protocols/websocket/tests/
37+
```
38+
39+
### Development Dependencies
40+
- Install dev dependencies: `pip install -e .[dev]`
41+
- Key dev tools: pytest, pytest-asyncio, pytest-aiohttp, pytest-cov, coverage, fastapi, uvicorn
42+
43+
## Architecture Overview
44+
45+
### Core Components
46+
47+
**Client Architecture (`src/utcp/client/`)**:
48+
- `UtcpClient`: Main entry point for UTCP ecosystem interaction
49+
- `UtcpClientConfig`: Pydantic model for client configuration
50+
- `ClientTransportInterface`: Abstract base for transport implementations
51+
- `ToolRepository`: Interface for storing/retrieving tools (default: `InMemToolRepository`)
52+
- `ToolSearchStrategy`: Interface for tool search algorithms (default: `TagSearchStrategy`)
53+
54+
**Shared Models (`src/utcp/shared/`)**:
55+
- `Tool`: Core tool definition with inputs/outputs schemas
56+
- `Provider`: Defines communication protocols for tools
57+
- `UtcpManual`: Contains discovery information for tool collections
58+
- `Auth`: Authentication models (API key, Basic, OAuth2)
59+
60+
**Transport Layer (`src/utcp/client/transport_interfaces/`)**:
61+
Each transport handles protocol-specific communication:
62+
- `HttpClientTransport`: RESTful HTTP/HTTPS APIs
63+
- `CliTransport`: Command Line Interface tools
64+
- `SSEClientTransport`: Server-Sent Events
65+
- `StreamableHttpClientTransport`: HTTP chunked transfer
66+
- `MCPTransport`: Model Context Protocol interoperability
67+
- `TextTransport`: Local file-based tool definitions
68+
- `GraphQLClientTransport`: GraphQL APIs
69+
70+
### Key Design Patterns
71+
72+
**Provider Registration**: Tools are discovered via `UtcpManual` objects from providers, then registered in the client's `ToolRepository`.
73+
74+
**Namespaced Tool Calling**: Tools are called using format `provider_name.tool_name` to avoid naming conflicts.
75+
76+
**OpenAPI Auto-conversion**: HTTP providers can point to OpenAPI v3 specs for automatic tool generation.
77+
78+
**Extensible Authentication**: Support for API keys, Basic auth, and OAuth2 with per-provider configuration.
79+
80+
## Configuration
81+
82+
### Provider Configuration
83+
Tools are configured via `providers.json` files that specify:
84+
- Provider name and type
85+
- Connection details (URL, method, etc.)
86+
- Authentication configuration
87+
- Tool discovery endpoints
88+
89+
### Client Initialization
90+
```python
91+
client = await UtcpClient.create(
92+
config={
93+
"providers_file_path": "./providers.json",
94+
"load_variables_from": [{"type": "dotenv", "env_file_path": ".env"}]
95+
}
96+
)
97+
```
98+
99+
## File Structure
100+
101+
- `src/utcp/client/`: Client implementation and transport interfaces
102+
- `src/utcp/shared/`: Shared models and utilities
103+
- `tests/`: Comprehensive test suite with transport-specific tests
104+
- `example/`: Complete usage examples including LLM integration
105+
- `scripts/`: Utility scripts for OpenAPI conversion and API fetching
106+
107+
## Important Implementation Notes
108+
109+
- All async operations use `asyncio`
110+
- Pydantic models throughout for validation and serialization
111+
- Transport interfaces are protocol-agnostic and swappable
112+
- Tool search supports tag-based ranking and keyword matching
113+
- Variable substitution in configuration supports environment variables and .env files

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ UTCP supports multiple communication protocols through dedicated plugins:
8686
| [`utcp-cli`](plugins/communication_protocols/cli/) | Command-line tools | ✅ Stable | [CLI Plugin README](plugins/communication_protocols/cli/README.md) |
8787
| [`utcp-mcp`](plugins/communication_protocols/mcp/) | Model Context Protocol | ✅ Stable | [MCP Plugin README](plugins/communication_protocols/mcp/README.md) |
8888
| [`utcp-text`](plugins/communication_protocols/text/) | Local file-based tools | ✅ Stable | [Text Plugin README](plugins/communication_protocols/text/README.md) |
89+
| [`utcp-websocket`](plugins/communication_protocols/websocket/) | WebSocket real-time bidirectional communication | ✅ Stable | [WebSocket Plugin README](plugins/communication_protocols/websocket/README.md) |
8990
| [`utcp-socket`](plugins/communication_protocols/socket/) | TCP/UDP protocols | 🚧 In Progress | [Socket Plugin README](plugins/communication_protocols/socket/README.md) |
9091
| [`utcp-gql`](plugins/communication_protocols/gql/) | GraphQL APIs | 🚧 In Progress | [GraphQL Plugin README](plugins/communication_protocols/gql/README.md) |
9192

‎example/src/websocket_example/README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# WebSocket Transport Example
2+
3+
This example demonstrates how to use the UTCP WebSocket transport for real-time communication.
4+
5+
## Overview
6+
7+
The WebSocket transport provides:
8+
- Real-time bidirectional communication
9+
- Tool discovery via WebSocket handshake
10+
- Streaming tool execution
11+
- Authentication support (API Key, Basic Auth, OAuth2)
12+
- Automatic reconnection and keep-alive
13+
14+
## Files
15+
16+
- `websocket_server.py` - Mock WebSocket server implementing UTCP protocol
17+
- `websocket_client.py` - Client example using WebSocket transport
18+
- `providers.json` - WebSocket provider configuration
19+
20+
## Protocol
21+
22+
The UTCP WebSocket protocol uses JSON messages:
23+
24+
### Tool Discovery
25+
```json
26+
// Client sends:
27+
{"type": "discover", "request_id": "unique_id"}
28+
29+
// Server responds:
30+
{
31+
"type": "discovery_response",
32+
"request_id": "unique_id",
33+
"tools": [...]
34+
}
35+
```
36+
37+
### Tool Execution
38+
```json
39+
// Client sends:
40+
{
41+
"type": "call_tool",
42+
"request_id": "unique_id",
43+
"tool_name": "tool_name",
44+
"arguments": {...}
45+
}
46+
47+
// Server responds:
48+
{
49+
"type": "tool_response",
50+
"request_id": "unique_id",
51+
"result": {...}
52+
}
53+
```
54+
55+
## Running the Example
56+
57+
1. Start the mock WebSocket server:
58+
```bash
59+
python websocket_server.py
60+
```
61+
62+
2. In another terminal, run the client:
63+
```bash
64+
python websocket_client.py
65+
```
66+
67+
## Configuration
68+
69+
The `providers.json` shows how to configure WebSocket providers with authentication:
70+
71+
```json
72+
[
73+
{
74+
"name": "websocket_tools",
75+
"provider_type": "websocket",
76+
"url": "ws://localhost:8765/ws",
77+
"auth": {
78+
"auth_type": "api_key",
79+
"api_key": "your-api-key",
80+
"var_name": "X-API-Key",
81+
"location": "header"
82+
},
83+
"keep_alive": true,
84+
"protocol": "utcp-v1"
85+
}
86+
]
87+
```

‎example/src/websocket_example/providers.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[
2+
{
3+
"name": "websocket_tools",
4+
"provider_type": "websocket",
5+
"url": "ws://localhost:8765/ws",
6+
"keep_alive": true,
7+
"headers": {
8+
"User-Agent": "UTCP-WebSocket-Client/1.0"
9+
}
10+
}
11+
]

0 commit comments

Comments
 (0)