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

[h3xxit]

• Add OpenAPI compatibility documentation

• Add OpenAPI compatibility section explaining UTCP as agent-focused extension
• Include minimal OpenAPI ingestion example in Quick Start
• Position information early in documentation for better user understanding

• Clarify OpenAPI conversion is optional

• Change 'are automatically converted' to 'can be automatically converted'
• More accurate description of optional conversion process

• Emphasize zero infrastructure requirement

• Add 'or additional infrastructure' to OpenAPI compatibility section
• Reinforces UTCP's core value proposition of no wrapper tax

• Update index.md

---

---

Summary by cubic

Add OpenAPI compatibility docs that explain UTCP’s agent-focused extensions (tags, average_response_size, multi-protocol, execution hints) and its backward compatibility. Quick Start now shows how to use an OpenAPI endpoint or convert a spec to a UTCP manual, clarifies conversion is optional, and confirms no additional infrastructure is required.

[cubic-dev-ai]

4 issues found across 1 file

_{React with 👍 or 👎 to teach cubic. You can also tag @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

[cubic-dev-ai]

Mentioning gRPC here implies current support, but the Supported Protocols table below does not list gRPC; clarify status or remove gRPC to avoid confusion.

Prompt for AI agents

Address the following comment on docs/index.md at line 33:

<comment>Mentioning gRPC here implies current support, but the Supported Protocols table below does not list gRPC; clarify status or remove gRPC to avoid confusion.</comment>

<file context>
@@ -28,6 +28,10 @@ UTCP acts as a **&quot;manual&quot;** that tells agents how to call your tools directly:
 
+## 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 (CLI, gRPC, WebSocket), 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)
</file context>

Suggested change

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 (CLI, gRPC, WebSocket), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes or additional infrastructure.

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 (CLI, WebSocket), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes or additional infrastructure.

[cubic-dev-ai]

Use HTTPS for the GitHub OpenAPI endpoint to avoid redirects/failures and align with the later example.

Prompt for AI agents

Address the following comment on docs/index.md at line 53:

<comment>Use HTTPS for the GitHub OpenAPI endpoint to avoid redirects/failures and align with the later example.</comment>

<file context>
@@ -44,7 +48,12 @@ npm install @utcp/core @utcp/http
-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`
+
+
</file context>

Suggested change

	**Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json`
	**Generate OpenAPI endpoint**: `GET https://api.github.com/openapi.json`

[cubic-dev-ai]

Trailing comma makes this JSON invalid; remove the comma after the last property.

Prompt for AI agents

Address the following comment on docs/index.md at line 122:

<comment>Trailing comma makes this JSON invalid; remove the comma after the last property.</comment>

<file context>
@@ -72,25 +81,50 @@ Add a discovery endpoint to your existing API:
+  &quot;manual_call_templates&quot;: [{
+    &quot;name&quot;: &quot;github_manual&quot;, 
+    &quot;call_template_type&quot;: &quot;text&quot;,
+    &quot;file_path&quot;: &quot;./github_manual.json&quot;,
+  }]
+}
</file context>

Suggested change

	"file_path": "./github_manual.json",
	"file_path": "./github_manual.json"

[cubic-dev-ai]

JSON example includes a // comment, which is invalid JSON and will break copy-paste usage; move the note outside the code block or remove it.

Prompt for AI agents

Address the following comment on docs/index.md at line 95:

<comment>JSON example includes a // comment, which is invalid JSON and will break copy-paste usage; move the note outside the code block or remove it.</comment>

<file context>
@@ -72,25 +81,50 @@ Add a discovery endpoint to your existing API:
     &quot;name&quot;: &quot;weather_api&quot;, 
     &quot;call_template_type&quot;: &quot;http&quot;,
-    &quot;url&quot;: &quot;http://localhost:8000/utcp&quot;,
+    &quot;url&quot;: &quot;http://localhost:8000/utcp&quot;, // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically
     &quot;http_method&quot;: &quot;GET&quot;
   }]
</file context>

Suggested change

	"url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically
	"url": "http://localhost:8000/utcp",

[perrozzi]

fyi there seems to be a problem with some markdown code, cfr section below rendered as code inside https://www.utcp.io/

That's it! Your tool is now discoverable and callable by any UTCP client.

Key Benefits

Benefit	Description
🚀 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
⚡ Easy Integration	Add one endpoint, no infrastructure changes
📈 Scalable	Leverage your existing scaling and monitoring

How It Works

graph LR
    A[AI Agent] -->|1. Discover| B[UTCP Manual]
    B -->|2. Learn| C[Tool Definitions]
    A -->|3. Call Directly| D[Your API]
    D -->|4. Response| A

Loading