@@ -7,10 +7,23 @@ This repository contains the official specification documentation for the Univer
77UTCP 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:
88
99- Tool discovery mechanisms
10- - Tool call formats
11- - Provider configuration
12- - Authentication methods
13- - Response handling
10+ - Tool call formats and templates
11+ - Plugin-based architecture for extensibility
12+ - Enhanced authentication methods
13+ - Comprehensive error handling
14+ - Response processing and validation
15+
16+ ## Version 1.0 Features
17+
18+ UTCP v1.0 introduces significant architectural improvements:
19+
20+ - ** Plugin Architecture** : Core functionality split into pluggable components for better modularity
21+ - ** Enhanced Data Models** : Improved Pydantic models with comprehensive validation
22+ - ** Multiple Protocol Support** : HTTP, CLI, WebSocket, Text, and MCP protocols via plugins
23+ - ** Advanced Authentication** : Expanded authentication options including API key, OAuth, and custom auth
24+ - ** Better Error Handling** : Specific exception types for different error scenarios
25+ - ** Performance Optimizations** : Optimized client and protocol implementations
26+ - ** Async/Await Support** : Full asynchronous client interface for better performance
1427
1528## Contributing to the Specification
1629
@@ -28,15 +41,35 @@ When contributing, please follow these guidelines:
2841- Include examples when adding new features or concepts
2942- Update relevant sections to maintain consistency across the documentation
3043
44+ ## Installation and Usage
45+
46+ ### Core Package Installation
47+
48+ ``` bash
49+ # Install the core UTCP package
50+ pip install utcp
51+
52+ # Install protocol plugins as needed
53+ pip install utcp-http utcp-cli utcp-websocket utcp-text utcp-mcp
54+ ```
55+
56+ ### Migration from v0.1 to v1.0
57+
58+ If you're upgrading from UTCP v0.1, please see our comprehensive [ Migration Guide] ( docs/migration-v0.1-to-v1.0.md ) which covers:
59+
60+ - Breaking changes and architectural improvements
61+ - Step-by-step migration instructions
62+ - Configuration and manual format updates
63+ - Common migration issues and solutions
64+
3165## Building the Documentation Locally
3266
3367### Prerequisites
3468
3569To build and preview the documentation site locally, you'll need:
3670
37- - Ruby version 2.5.0 or higher
38- - RubyGems
39- - Bundler
71+ - Node.js version 18.0 or higher
72+ - npm or yarn package manager
4073
4174### Setup
4275
@@ -48,54 +81,63 @@ To build and preview the documentation site locally, you'll need:
4881
49822 . Install dependencies:
5083 ``` bash
51- bundle install
84+ npm install
5285 ```
5386
5487### Running the Documentation Site
5588
5689To build and serve the site locally:
5790
5891``` bash
59- bundle exec jekyll serve
92+ npm start
6093```
6194
62- This will start a local web server at ` http://localhost:4000 ` where you can preview the documentation.
95+ This will start a local development server at ` http://localhost:3000 ` where you can preview the documentation.
6396
6497## Documentation Structure
6598
6699The UTCP documentation is organized as follows:
67100
68- - ` index.md ` : Homepage and introduction to UTCP
69101- ` docs/ `
102+ - ` index.md ` : Homepage and introduction to UTCP
70103 - ` introduction.md ` : Detailed introduction and core concepts
71104 - ` for-tool-providers.md ` : Guide for implementing tool providers
72105 - ` for-tool-callers.md ` : Guide for implementing tool callers
73- - ` providers/ ` : Documentation for each provider type
74- - ` http.md ` : HTTP provider
75- - ` websocket.md ` : WebSocket provider
76- - ` cli.md ` : CLI provider
77- - ` sse.md ` : Server-Sent Events provider
78- - etc.
106+ - ` migration-v0.1-to-v1.0.md ` : Comprehensive migration guide from v0.1 to v1.0
107+ - ` protocols/ ` : Documentation for each protocol type
108+ - ` http.md ` : HTTP protocol implementation
109+ - ` websocket.md ` : WebSocket protocol implementation
110+ - ` cli.md ` : CLI protocol implementation
111+ - ` sse.md ` : Server-Sent Events protocol implementation
112+ - ` text.md ` : Text protocol implementation
113+ - ` mcp.md ` : Model Context Protocol implementation
114+ - ` api/ ` : API reference documentation
115+ - ` core/ ` : Core API documentation
116+ - ` plugins/ ` : Plugin API documentation
79117 - ` implementation.md ` : Implementation guidelines and best practices
118+ - ` versioned_docs/ ` : Version-specific documentation for backwards compatibility
80119
81120## Working with the Specification
82121
83122### Modifying the Documentation
84123
85- The documentation is written in Markdown format with Jekyll front matter . When making changes:
124+ The documentation is built with Docusaurus and written in Markdown format . When making changes:
86125
871261 . Ensure your Markdown follows the established style
881272 . Preview changes locally before submitting PRs
89- 3 . Keep examples up-to-date with the latest specification
90- 4 . Update navigation items in ` _config.yml ` if adding new pages
128+ 3 . Keep examples up-to-date with the latest specification (v1.0)
129+ 4 . Update navigation items in ` sidebars.ts ` if adding new pages
130+ 5 . Consider version compatibility when making breaking changes
91131
92132### File Organization
93133
94134When adding new documentation:
95135
96- - Place provider-specific documentation in ` docs/providers/ `
136+ - Place protocol-specific documentation in ` docs/protocols/ `
137+ - Place API documentation in ` docs/api/core/ ` or ` docs/api/plugins/ `
97138- Use consistent front matter with appropriate navigation ordering
98- - Include tags for improved searchability on GitHub Pages
139+ - Include tags for improved searchability
140+ - Consider versioning for breaking changes using ` versioned_docs/ `
99141
100142## Version Control
101143
0 commit comments