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 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. 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. The contents of docs/api/** and versioned_docs/version-*/api/** are auto-generated from docstrings in 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
• UTCP Website
• Reference Implementations
• Community Discussions