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

# 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 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:

   git clone https://github.com/universal-tool-calling-protocol/utcp-specification.git
   cd utcp-specification

2. Install dependencies:

   npm install

Running the Documentation Site

To build and serve the site locally:

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
• UTCP Website
• Reference Implementations
• Community Discussions