OpenAPI docs and fix a lot of issues (#47)

docs/for-tool-providers.md

@@ -45,7 +45,7 @@ As a tool provider, you'll create a **UTCP Manual** - a standardized description
       },
       "tool_call_template": {
         "call_template_type": "http",
-        "url": "https://api.example.com/users/${user_id}",
+        "url": "https://api.example.com/users/{user_id}",
         "http_method": "GET"
       }
     }
@@ -236,11 +236,7 @@ Use `${VARIABLE_NAME}` syntax for dynamic values:
 
 ```json
 {
-  "url": "https://api.example.com/users/${user_id}",
-  "body": {
-    "name": "${name}",
-    "email": "${email}"
-  }
+  "url": "https://api.example.com/users/{user_id}"
 }
 ```
 
@@ -270,8 +266,7 @@ Use `${VARIABLE_NAME}` syntax for dynamic values:
       "name": "get_data",
       "tool_call_template": {
         "call_template_type": "http",
-        "url": "${base_url}/data",
-        "timeout": "${timeout}"
+        "url": "${base_url}/data"
       }
     }
   ]
@@ -327,7 +322,7 @@ The UTCP manual describes how to call your existing endpoints:
       },
       "tool_call_template": {
         "call_template_type": "http",
-        "url": "https://api.example.com/users/${user_id}",
+        "url": "https://api.example.com/users/{user_id}",
         "http_method": "GET",
         "auth": {
           "auth_type": "api_key",
@@ -550,9 +545,7 @@ Test your manual with UTCP clients:
     "call_template_type": "http",
     "url": "https://api.example.com/batch",
     "http_method": "POST",
-    "body": {
-      "items": "${items}"
-    }
+    "body_field": "items"
   }
 }
 ```

docs/implementation.md

@@ -146,7 +146,6 @@ Call templates define how to invoke tools using specific protocols:
 }
 
 Tool arguments not used in the URL path or headers will be sent as query parameters for GET requests, or in the request body for POST/PUT/PATCH requests. The `body_field` specifies which tool argument contains the data for the request body.
-}
 ```
 
 #### CLI Call Template

docs/index.md

@@ -28,6 +28,10 @@ UTCP acts as a **"manual"** that tells agents how to call your tools directly:
 *"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."*
 :::
 
+## OpenAPI Compatibility
+
+UTCP extends OpenAPI for AI agents while maintaining full backward compatibility. Where OpenAPI describes APIs for human developers, UTCP adds agent-focused enhancements: `tags` for categorization, `average_response_size` for resource planning, multi-protocol support (HTTP, CLI, gRPC, MCP), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes or additional infrastructure.
+
 ## Quick Start (5 Minutes)
 
 ### 1. Install UTCP
@@ -44,7 +48,12 @@ npm install @utcp/core @utcp/http
 
 ### 2. Expose Your First Tool
 
-Add a discovery endpoint to your existing API:
+**Option A: Discovery via existing OpenAPI spec**
+
+**Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json`
+
+
+**Option B: Add a discovery endpoint to your existing API**
 
 **Add endpoint**: `GET /utcp`
 **Return your UTCP manual**:
@@ -72,31 +81,55 @@ Add a discovery endpoint to your existing API:
     "var_name": "appid",
     "location": "query"
   }
-    }
-  }]
 }
 ```
 
 ### 3. Call Your Tool
 
-**Configure UTCP client**:
+**Option A: Configure UTCP client**:
 ```json
 {
   "manual_call_templates": [{
     "name": "weather_api", 
     "call_template_type": "http",
-    "url": "http://localhost:8000/utcp",
+    "url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically
     "http_method": "GET"
   }]
 }
 ```
 
+**Option B: Convert OpenAPI spec to UTCP manual manually**
+
+```python
+async def convert_api():
+    async with aiohttp.ClientSession() as session:
+        async with session.get("https://api.github.com/openapi.json") as response:
+            openapi_spec = await response.json()
+
+    converter = OpenApiConverter(openapi_spec)
+    manual = converter.convert()
+
+    print(f"Generated {len(manual.tools)} tools from GitHub API!")
+    return manual
+```
+
+Then save that to a text file and load it with the text configuration:
+```json
+{
+  "manual_call_templates": [{
+    "name": "github_manual", 
+    "call_template_type": "text",
+    "file_path": "./github_manual.json",
+  }]
+}
+```
+
+
 **Call the tool**:
 1. Initialize UTCP client with configuration
 2. Discover tools from weather API  
 3. Call `get_weather` tool with location parameter
 4. Receive weather data response
-```
 
 **That's it!** Your tool is now discoverable and callable by any UTCP client.
 
@@ -106,7 +139,7 @@ Add a discovery endpoint to your existing API:
 |---------|-------------|
 | **🚀 Zero Latency Overhead** | Direct tool calls, no proxy servers |
 | **🔒 Native Security** | Use your existing authentication and authorization |
-| **🌐 Protocol Flexibility** | HTTP, WebSocket, CLI, GraphQL, and more |
+| **🌐 Protocol Flexibility** | HTTP, MCP, CLI, GraphQL, and more |
 | **⚡ Easy Integration** | Add one endpoint, no infrastructure changes |
 | **📈 Scalable** | Leverage your existing scaling and monitoring |
 
@@ -132,7 +165,6 @@ UTCP supports multiple communication protocols through plugins:
 | Protocol | Use Case | Plugin | Status |
 |----------|----------|--------|--------|
 | **[HTTP](./protocols/http.md)** | REST APIs, webhooks | `utcp-http` | ✅ Stable |
-| **[WebSocket](./protocols/websocket.md)** | Real-time communication | `utcp-websocket` | ✅ Stable |
 | **[CLI](./protocols/cli.md)** | Command-line tools | `utcp-cli` | ✅ Stable |
 | **[Server-Sent Events](./protocols/streamable-http.md)** | Streaming data | `utcp-http` | ✅ Stable |
 | **[Text Files](./protocols/text.md)** | File reading | `utcp-text` | ✅ Stable |
@@ -151,7 +183,7 @@ UTCP v1.0 features a modular, plugin-based architecture:
 - **[UTCP Client](./api/core/utcp/utcp_client.md)**: Tool discovery and execution engine
 
 ### Plugin System
-- **Protocol Plugins**: HTTP, WebSocket, CLI, etc.
+- **Protocol Plugins**: HTTP, MCP, CLI, etc.
 - **Custom Protocols**: Extend with your own communication methods
 - **Tool Repositories**: Pluggable storage for tool definitions
 - **Search Strategies**: Customizable tool discovery algorithms

docs/migration-v0.1-to-v1.0.md

@@ -139,7 +139,7 @@ load_variables_from:
 ```json
 {
   "manual_version": "1.0.0",
-  "utcp_version": "1.0.1",
+  "utcp_version": "0.2.0",
   "info": {
     "title": "Weather API",
     "version": "1.0.0",
@@ -174,7 +174,6 @@ load_variables_from:
         "var_name": "appid",
         "location": "query"
       }
-      }
     }
   ]
 }