Skip to content

Commit 6c15896

Browse files
perrozziperrozzi
committed
Improve landing page, security, and UTCP vs MCP documentation
- Rewrite docs/index.md with better structure, clear value proposition, and navigation - Enhance docs/security.md with comprehensive protocol-specific security guidance - Improve docs/utcp-vs-mcp.md with technical depth, migration guidance, and decision framework - Add language specification notes consistently across documentation - Include practical examples and cross-references throughout
1 parent 313b30a commit 6c15896

File tree

3 files changed

+1297
-241
lines changed

3 files changed

+1297
-241
lines changed

‎docs/index.md‎

Lines changed: 173 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -4,152 +4,221 @@ title: Introduction
44
sidebar_position: 1
55
---
66

7-
# Introduction to UTCP 1.0
7+
# Universal Tool Calling Protocol (UTCP)
88

9-
The Universal Tool Calling Protocol (UTCP) is a lightweight, secure, and scalable standard for defining and interacting with tools across a wide variety of communication protocols. Version 1.0 introduces a modular core with a plugin-based architecture, making it more extensible, testable, and easier to package.
10-
11-
## Core Components
9+
:::info Language Examples
10+
This documentation uses **Python** examples. UTCP is available in multiple languages - see [TypeScript](https://github.com/universal-tool-calling-protocol/typescript-utcp), [Go](https://github.com/universal-tool-calling-protocol/go-utcp), and other implementations in the [UTCP GitHub organization](https://github.com/universal-tool-calling-protocol).
11+
:::
1212

13-
UTCP consists of four main components:
13+
UTCP is a lightweight, secure, and scalable standard that enables AI agents and applications to discover and call tools directly using their native protocols - **no wrapper servers required**.
1414

15-
1. [**Manuals**](./api/core/utcp/data/utcp_manual.md): The standard tool provider description format that contains tool definitions
16-
2. [**Tools**](./api/core/utcp/data/tool.md): The individual capabilities that can be called
17-
3. [**Call Templates**](./api/core/utcp/data/call_template.md): The communication configurations that specify how tools are accessed. Concretely this maps a tool name and provided arguments to an actual API request in a communication protocol.
18-
4. [**UtcpClient**](./api/core/utcp/utcp_client.md): The client that calls tools using the call templates.
15+
## Why UTCP?
1916

20-
## The "Manual" Approach
17+
### The Problem with Current Approaches
18+
Most tool integration solutions force you to:
19+
- Build and maintain wrapper servers for every tool
20+
- Route all traffic through a middleman protocol
21+
- Reimplement existing authentication and security
22+
- Accept additional latency and complexity
2123

22-
UTCP's fundamental philosophy is to act as a descriptive manual rather than a prescriptive middleman:
24+
### The UTCP Solution
25+
UTCP acts as a **"manual"** that tells agents how to call your tools directly:
2326

24-
:::note
25-
A UTCP Manual tells an agent: "Here is a tool. Here is its native endpoint (HTTP, WebSocket, CLI, etc.), and here is how to call it directly."
27+
:::tip Core Philosophy
28+
*"If a human can call your API, an AI agent should be able to call it too - with the same security and no additional infrastructure."*
2629
:::
2730

28-
This approach eliminates the need for wrapper servers and allows direct communication between agents and tools.
29-
30-
## New Architecture in 1.0
31-
32-
UTCP has been refactored into a core library and a set of optional plugins:
31+
## Quick Start (5 Minutes)
3332

34-
### Core Package (`utcp`)
35-
- **Data Models**: Pydantic models for [`Tool`](./api/core/utcp/data/tool.md), [`CallTemplate`](./api/core/utcp/data/call_template.md), [`UtcpManual`](./api/core/utcp/data/utcp_manual.md), and [`Auth`](./api/core/utcp/data/auth.md)
36-
- **Pluggable Interfaces**: [`CommunicationProtocol`](./api/core/utcp/interfaces/communication_protocol.md), [`ConcurrentToolRepository`](./api/core/utcp/interfaces/concurrent_tool_repository.md), [`ToolSearchStrategy`](./api/core/utcp/interfaces/tool_search_strategy.md), [`VariableSubstitutor`](./api/core/utcp/interfaces/variable_substitutor.md), [`ToolPostProcessor`](./api/core/utcp/interfaces/tool_post_processor.md)
37-
- **Default Implementations**: [`UtcpClient`](./api/core/utcp/utcp_client.md), [`InMemToolRepository`](./api/core/utcp/implementations/in_mem_tool_repository.md), [`TagAndDescriptionWordMatchStrategy`](./api/core/utcp/implementations/tag_search.md)
33+
### 1. Install UTCP
3834

39-
### Protocol Plugins
40-
- `utcp-http`: Supports HTTP, SSE, and streamable HTTP, plus an OpenAPI converter
41-
- `utcp-cli`: For wrapping local command-line tools
42-
- `utcp-mcp`: For interoperability with the Model Context Protocol (MCP)
43-
- `utcp-text`: For reading text files
44-
- `utcp-socket`: TCP and UDP protocols (work in progress)
45-
- `utcp-gql`: GraphQL (work in progress)
46-
47-
## Minimal Example
48-
49-
Let's see how easy it is to use UTCP with a minimal example.
35+
```bash
36+
# Core library + HTTP support
37+
pip install utcp utcp-http
38+
```
5039

51-
### 1. Defining a Tool (Tool Provider)
40+
### 2. Expose Your First Tool
5241

53-
Create a simple HTTP endpoint that serves a UTCP Manual (JSON):
42+
Add a discovery endpoint to your existing API:
5443

5544
```python
56-
# app.py
5745
from fastapi import FastAPI
5846

5947
app = FastAPI()
6048

49+
# Your existing API endpoint (unchanged)
50+
@app.get("/weather")
51+
def get_weather(location: str):
52+
return {"temperature": 22, "conditions": "Sunny"}
53+
54+
# Add UTCP discovery endpoint
6155
@app.get("/utcp")
62-
def utcp_discovery():
56+
def utcp_manual():
6357
return {
6458
"manual_version": "1.0.0",
6559
"utcp_version": "1.0.1",
66-
"tools": [
67-
{
68-
"name": "get_weather",
69-
"description": "Get current weather for a location",
70-
"inputs": {
71-
"type": "object",
72-
"properties": {
73-
"location": {
74-
"type": "string",
75-
"description": "City name"
76-
}
77-
},
78-
"required": ["location"]
79-
},
80-
"outputs": {
81-
"type": "object",
82-
"properties": {
83-
"temperature": {"type": "number"},
84-
"conditions": {"type": "string"}
85-
}
86-
},
87-
"tool_call_template": {
88-
"call_template_type": "http",
89-
"url": "https://example.com/api/weather",
90-
"http_method": "GET"
91-
}
60+
"tools": [{
61+
"name": "get_weather",
62+
"description": "Get current weather for a location",
63+
"inputs": {
64+
"type": "object",
65+
"properties": {"location": {"type": "string"}},
66+
"required": ["location"]
67+
},
68+
"tool_call_template": {
69+
"call_template_type": "http",
70+
"url": "http://localhost:8000/weather",
71+
"http_method": "GET",
72+
"query_params": {"location": "${location}"}
9273
}
93-
]
74+
}]
9475
}
95-
96-
# Implement the actual weather API endpoint
97-
@app.get("/api/weather")
98-
def get_weather(location: str):
99-
# In a real app, you'd fetch actual weather data
100-
return {"temperature": 22.5, "conditions": "Sunny"}
101-
```
102-
103-
Run the server:
104-
105-
```bash
106-
uvicorn app:app --reload
10776
```
10877

109-
### 2. Using the Tool (Client)
78+
### 3. Call Your Tool
11079

11180
```python
112-
# client.py
11381
import asyncio
11482
from utcp.utcp_client import UtcpClient
115-
from utcp_http.http_call_template import HttpCallTemplate
11683

11784
async def main():
118-
# Create a UTCP client with configuration
11985
client = await UtcpClient.create(config={
120-
"manual_call_templates": [
121-
{
122-
"name": "weather_service",
123-
"call_template_type": "http",
124-
"http_method": "GET",
125-
"url": "http://localhost:8000/utcp"
126-
}
127-
]
86+
"manual_call_templates": [{
87+
"name": "weather_api",
88+
"call_template_type": "http",
89+
"url": "http://localhost:8000/utcp",
90+
"http_method": "GET"
91+
}]
12892
})
129-
130-
# Tools are automatically registered from the manual call templates
131-
# Call a tool by its namespaced name: {manual_name}.{tool_name}
93+
13294
result = await client.call_tool(
133-
"weather_service.get_weather",
95+
"weather_api.get_weather",
13496
tool_args={"location": "San Francisco"}
13597
)
136-
print(f"Weather: {result['temperature']}°C, {result['conditions']}")
98+
print(f"Weather: {result}")
13799

138-
if __name__ == "__main__":
139-
asyncio.run(main())
100+
asyncio.run(main())
140101
```
141102

142-
Run the client:
103+
**That's it!** Your tool is now discoverable and callable by any UTCP client.
143104

144-
```bash
145-
python client.py
105+
## Key Benefits
106+
107+
| Benefit | Description |
108+
|---------|-------------|
109+
| **🚀 Zero Latency Overhead** | Direct tool calls, no proxy servers |
110+
| **🔒 Native Security** | Use your existing authentication and authorization |
111+
| **🌐 Protocol Flexibility** | HTTP, WebSocket, CLI, GraphQL, and more |
112+
| **⚡ Easy Integration** | Add one endpoint, no infrastructure changes |
113+
| **📈 Scalable** | Leverage your existing scaling and monitoring |
114+
115+
## How It Works
116+
117+
```mermaid
118+
graph LR
119+
A[AI Agent] -->|1. Discover| B[UTCP Manual]
120+
B -->|2. Learn| C[Tool Definitions]
121+
A -->|3. Call Directly| D[Your API]
122+
D -->|4. Response| A
146123
```
147124

148-
## Benefits of the UTCP Approach
125+
1. **Discovery**: Agent fetches your UTCP manual
126+
2. **Learning**: Agent understands how to call your tools
127+
3. **Direct Calling**: Agent calls your API directly using native protocols
128+
4. **Response**: Your API responds normally
129+
130+
## Supported Protocols
131+
132+
UTCP supports multiple communication protocols through plugins:
133+
134+
| Protocol | Use Case | Plugin | Status |
135+
|----------|----------|--------|--------|
136+
| **[HTTP](./providers/http.md)** | REST APIs, webhooks | `utcp-http` | ✅ Stable |
137+
| **[WebSocket](./providers/websocket.md)** | Real-time communication | `utcp-websocket` | ✅ Stable |
138+
| **[CLI](./providers/cli.md)** | Command-line tools | `utcp-cli` | ✅ Stable |
139+
| **[Server-Sent Events](./providers/sse.md)** | Streaming data | `utcp-http` | ✅ Stable |
140+
| **[Text Files](./providers/text.md)** | File reading | `utcp-text` | ✅ Stable |
141+
| **[MCP](./providers/mcp.md)** | MCP interoperability | `utcp-mcp` | ✅ Stable |
142+
143+
[View all protocols →](./providers/index.md)
144+
145+
## Architecture Overview
146+
147+
UTCP v1.0 features a modular, plugin-based architecture:
148+
149+
### Core Components
150+
- **[Manuals](./api/core/utcp/data/utcp_manual.md)**: Tool definitions and metadata
151+
- **[Tools](./api/core/utcp/data/tool.md)**: Individual callable capabilities
152+
- **[Call Templates](./api/core/utcp/data/call_template.md)**: Protocol-specific call instructions
153+
- **[UTCP Client](./api/core/utcp/utcp_client.md)**: Tool discovery and execution engine
154+
155+
### Plugin System
156+
- **Protocol Plugins**: HTTP, WebSocket, CLI, etc.
157+
- **Custom Protocols**: Extend with your own communication methods
158+
- **Tool Repositories**: Pluggable storage for tool definitions
159+
- **Search Strategies**: Customizable tool discovery algorithms
160+
161+
[Learn more about the architecture →](./api/index.md)
162+
163+
## Who Should Use UTCP?
164+
165+
### 🛠️ Tool Providers
166+
You have APIs, services, or tools that you want AI agents to use:
167+
- **Existing API owners** - Expose your REST APIs to AI agents
168+
- **SaaS providers** - Make your services AI-accessible
169+
- **Enterprise teams** - Enable internal tool usage by AI systems
170+
171+
[**Get started as a tool provider →**](./for-tool-providers.md)
149172

150-
1. **Direct Communication**: The client calls the tool's native endpoint directly
151-
2. **No Wrapper Infrastructure**: No need to build and maintain wrapper servers
152-
3. **Leverage Existing Systems**: Uses the tool's existing authentication, rate limiting, etc.
153-
4. **Flexible Protocol Support**: Works with any communication protocol (HTTP, WebSockets, CLI, etc.)
173+
### 🤖 Tool Consumers
174+
You're building AI agents or applications that need to call external tools:
175+
- **AI agent developers** - Give your agents access to external capabilities
176+
- **Application builders** - Integrate third-party tools seamlessly
177+
- **Enterprise developers** - Connect to internal and external services
178+
179+
[**Get started as a tool consumer →**](./implementation.md)
180+
181+
## UTCP vs Alternatives
182+
183+
| Feature | UTCP | MCP | Custom Wrappers |
184+
|---------|------|-----|-----------------|
185+
| **Infrastructure** | None required | Wrapper servers | Custom servers |
186+
| **Latency** | Direct calls | Double hop | Variable |
187+
| **Security** | Native | Reimplemented | Custom |
188+
| **Protocols** | Multiple | HTTP streaming | Single |
189+
| **Maintenance** | Minimal | High | Very high |
190+
191+
[**Detailed comparison with MCP →**](./utcp-vs-mcp.md)
192+
193+
## Next Steps
194+
195+
### For Tool Providers
196+
1. **[Read the provider guide](./for-tool-providers.md)** - Learn how to expose your tools
197+
2. **[Choose your protocol](./providers/index.md)** - Select the right communication method
198+
3. **[Implement your manual](./implementation.md)** - Add UTCP to your existing API
199+
4. **[Secure your tools](./security.md)** - Implement proper authentication
200+
201+
### For Tool Consumers
202+
1. **[Read the implementation guide](./implementation.md)** - Learn how to build UTCP clients
203+
2. **[Explore protocols](./providers/index.md)** - Understand available communication options
204+
3. **[Check examples](https://github.com/universal-tool-calling-protocol/python-utcp/tree/main/examples)** - See real-world implementations
205+
4. **[Join the community](https://discord.gg/ZpMbQ8jRbD)** - Get help and share experiences
206+
207+
### Migration from Other Systems
208+
- **[From UTCP v0.1](./migration-v0.1-to-v1.0.md)** - Upgrade to the latest version
209+
- **[From MCP](./providers/mcp.md)** - Migrate from Model Context Protocol
210+
- **[From custom solutions](./implementation.md)** - Replace existing tool integrations
211+
212+
## Community & Support
213+
214+
- **[GitHub Organization](https://github.com/universal-tool-calling-protocol)** - Source code and issues
215+
- **[Discord Community](https://discord.gg/ZpMbQ8jRbD)** - Real-time help and discussions
216+
- **[Tool Registry](https://utcp.io/registry)** - Discover available tools
217+
- **[RFC Process](./about/RFC.md)** - Contribute to the specification
218+
219+
---
154220

155-
In the following sections, we'll explore the details of UTCP's components and how to implement them in your applications.
221+
**Ready to get started?** Choose your path:
222+
- 🛠️ [**I want to expose my tools**](./for-tool-providers.md)
223+
- 🤖 [**I want to call tools**](./implementation.md)
224+
- 📚 [**I want to learn more**](./providers/index.md)

0 commit comments

Comments
 (0)