utcp-specification

# Universal Tool Calling Protocol (UTCP) Specification This repository contains the official specification documentation for the Universal Tool Calling Protocol (UTCP). UTCP is a modern, flexible, and scalable standard for defining and interacting with tools across various communication protocols. ## What is UTCP? UTCP provides a standardized way for AI systems and other clients to discover and call tools from different providers, regardless of the underlying protocol used (HTTP, WebSocket, CLI, etc.). This specification defines: - Tool discovery mechanisms - Tool call formats and templates - Plugin-based architecture for extensibility - Enhanced authentication methods - Comprehensive error handling - Response processing and validation ## Version 1.0 Features UTCP v1.0 introduces significant architectural improvements: - **Plugin Architecture**: Core functionality split into pluggable components for better modularity - **Enhanced Data Models**: Improved Pydantic models with comprehensive validation - **Multiple Protocol Support**: HTTP, CLI, WebSocket, Text, and MCP protocols via plugins - **Advanced Authentication**: Expanded authentication options including API key, OAuth, and custom auth - **Better Error Handling**: Specific exception types for different error scenarios - **Performance Optimizations**: Optimized client and protocol implementations - **Async/Await Support**: Full asynchronous client interface for better performance ## Contributing to the Specification We welcome contributions to the UTCP specification! Here's how you can contribute: 1. **Fork the repository**: Create your own fork of the specification repository 2. **Make your changes**: Update or add documentation as needed 3. **Submit a pull request**: Open a PR with your changes for review 4. **Participate in discussions**: Join the conversation about proposed changes When contributing, please follow these guidelines: - Ensure your changes align with the overall vision and goals of UTCP - Follow the established documentation structure and formatting - Include examples when adding new features or concepts - Update relevant sections to maintain consistency across the documentation ## Installation and Usage ### Core Package Installation ```bash # Install the core UTCP package pip install utcp # Install protocol plugins as needed pip install utcp-http utcp-cli utcp-websocket utcp-text utcp-mcp ``` ### Migration from v0.1 to v1.0 If you're upgrading from UTCP v0.1, please see our comprehensive [Migration Guide](docs/migration-v0.1-to-v1.0.md) which covers: - Breaking changes and architectural improvements - Step-by-step migration instructions - Configuration and manual format updates - Common migration issues and solutions ## Building the Documentation Locally ### Prerequisites To build and preview the documentation site locally, you'll need: - Node.js version 18.0 or higher - npm or yarn package manager ### Setup 1. Clone the repository: ```bash git clone https://github.com/universal-tool-calling-protocol/utcp-specification.git cd utcp-specification ``` 2. Install dependencies: ```bash npm install ``` ### Running the Documentation Site To build and serve the site locally: ```bash npm start ``` This will start a local development server at `http://localhost:3000` where you can preview the documentation. ## Documentation Structure The UTCP documentation is organized as follows: - `docs/` - `index.md`: Homepage and introduction to UTCP - `introduction.md`: Detailed introduction and core concepts - `for-tool-providers.md`: Guide for implementing tool providers - `for-tool-callers.md`: Guide for implementing tool callers - `migration-v0.1-to-v1.0.md`: Comprehensive migration guide from v0.1 to v1.0 - `protocols/`: Documentation for each protocol type - `http.md`: HTTP protocol implementation - `websocket.md`: WebSocket protocol implementation - `cli.md`: CLI protocol implementation - `sse.md`: Server-Sent Events protocol implementation - `text.md`: Text protocol implementation - `mcp.md`: Model Context Protocol implementation - `api/`: API reference documentation - `core/`: Core API documentation - `plugins/`: Plugin API documentation - `implementation.md`: Implementation guidelines and best practices - `versioned_docs/`: Version-specific documentation for backwards compatibility ## Working with the Specification ### Modifying the Documentation The documentation is built with Docusaurus and written in Markdown format. When making changes: 1. Ensure your Markdown follows the established style 2. Preview changes locally before submitting PRs 3. Keep examples up-to-date with the latest specification (v1.0) 4. Update navigation items in `sidebars.ts` if adding new pages 5. Consider version compatibility when making breaking changes ### File Organization When adding new documentation: - Place protocol-specific documentation in `docs/protocols/` - Place API documentation in `docs/api/core/` or `docs/api/plugins/` - Use consistent front matter with appropriate navigation ordering - Include tags for improved searchability - Consider versioning for breaking changes using `versioned_docs/` ## Version Control The UTCP specification follows semantic versioning: - Major versions (1.0, 2.0): Breaking changes to the protocol - Minor versions (1.1, 1.2): New features added in a backward-compatible manner - Patch versions (1.0.1, 1.0.2): Backward-compatible bug fixes and clarifications ## License This specification is distributed under the Mozilla Public License 2.0 (MPL-2.0). ## Additional Resources - [UTCP GitHub Organization](https://github.com/universal-tool-calling-protocol) - [UTCP Website](https://utcp.io) - [Reference Implementations](https://github.com/universal-tool-calling-protocol/python-utcp) - [Community Discussions](https://github.com/universal-tool-calling-protocol/utcp-specification/discussions)