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 repository is **dual-licensed by directory** to keep adoption friction low while respecting the upstream license of the reference implementation: - **Default license — [Apache License 2.0](LICENSE).** Covers everything in the repository *except* the `api/` documentation subtrees: the specification prose, protocol guides, RFC, blog posts, code examples (whether standalone files or fenced code blocks in Markdown), site source code, and build configuration. Implementers can quote, copy, and embed this content freely under Apache-2.0 terms. - **API reference docs — [Mozilla Public License 2.0](LICENSE-MPL).** The contents of `docs/api/**` and `versioned_docs/version-*/api/**` are auto-generated from docstrings in [python-utcp](https://github.com/universal-tool-calling-protocol/python-utcp), which is MPL-2.0-licensed. External contributors submit docstring changes under MPL-2.0, so the generated reference docs inherit that license. Each MPL-covered subtree contains its own `LICENSE` and `NOTICE.md`. The MPL-2.0 boundary is the `api/` directory — not a "code vs. prose" distinction. SPDX: `Apache-2.0 AND 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)