python-utcp: Instructions file for Claude Code

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

# 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

# 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