📚 Enhance v1.0 Documentation: Add Protocol Guides, Implementation Examples, and User Navigation #42
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add Hall of Fame
…tool-calling-protocol/dev Dev
- Add complete communication protocols documentation (HTTP, WebSocket, SSE, CLI, Text, MCP) - Add implementation guide with Python examples and multi-language references - Add for-tool-providers guide with practical examples - Add migration guide from v0.1 to v1.0 - Update sidebar navigation structure - Address incomplete current version documentation gap
- 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
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
| "input_file": {"type": "string"}, | ||
| "output_format": {"type": "string", "enum": ["json", "csv"]} | ||
| }, | ||
| "required": ["input_file"] |
Contributor
There was a problem hiding this comment.
output_format is referenced in args but not marked required, which can produce invalid calls when omitted; either require it or make the flag conditional.
Prompt for AI agents
Address the following comment on docs/providers/cli.md at line 163:
<comment>output_format is referenced in args but not marked required, which can produce invalid calls when omitted; either require it or make the flag conditional.</comment>
<file context>
@@ -0,0 +1,323 @@
+ "input_file": {"type": "string"},
+ "output_format": {"type": "string", "enum": ["json", "csv"]}
+ },
+ "required": ["input_file"]
+ },
+ "tool_call_template": {
</file context>
| { | ||
| "call_template_type": "cli", | ||
| "command": "python", | ||
| "args": ["-c", "import os; print(os.listdir('${path}'))"] |
Contributor
There was a problem hiding this comment.
Interpolating ${path} inside the Python -c code enables code injection if the value contains quotes or escapes; pass the path as an argument instead.
Prompt for AI agents
Address the following comment on docs/providers/cli.md at line 321:
<comment>Interpolating ${path} inside the Python -c code enables code injection if the value contains quotes or escapes; pass the path as an argument instead.</comment>
<file context>
@@ -0,0 +1,323 @@
+{
+ "call_template_type": "cli",
+ "command": "python",
+ "args": ["-c", "import os; print(os.listdir('${path}'))"]
+}
+```
</file context>
| ] | ||
| ) | ||
|
|
||
| client = await UtcpClient.create(config=config) |
Contributor
There was a problem hiding this comment.
Top-level await in Python example; needs to be inside an async function (or wrapped with asyncio.run).
Prompt for AI agents
Address the following comment on docs/implementation.md at line 347:
<comment>Top-level await in Python example; needs to be inside an async function (or wrapped with asyncio.run).</comment>
<file context>
@@ -0,0 +1,580 @@
+ ]
+)
+
+client = await UtcpClient.create(config=config)
+```
+
</file context>
| "http_method": "GET", | ||
| "query_params": { | ||
| "q": "${location}", | ||
| "appid": "${WEATHER_API_KEY}" |
Contributor
There was a problem hiding this comment.
API key is included twice (in query_params and via auth injection), which can cause duplication or confusion. Remove one of the two sources to avoid conflicts.
Prompt for AI agents
Address the following comment on docs/implementation.md at line 63:
<comment>API key is included twice (in query_params and via auth injection), which can cause duplication or confusion. Remove one of the two sources to avoid conflicts.</comment>
<file context>
@@ -0,0 +1,580 @@
+ "http_method": "GET",
+ "query_params": {
+ "q": "${location}",
+ "appid": "${WEATHER_API_KEY}"
+ }
+ }
</file context>
| from utcp_http.openapi_converter import OpenApiConverter | ||
|
|
||
| converter = OpenApiConverter() | ||
| manual = await converter.convert_openapi_to_manual( |
Contributor
There was a problem hiding this comment.
Example references an undocumented method convert_openapi_to_manual; API docs list OpenApiConverter.convert() instead, which may mislead users copying the snippet.
(Based on your team's feedback about providing accurate, practical implementation examples.)
Prompt for AI agents
Address the following comment on docs/providers/http.md at line 249:
<comment>Example references an undocumented method convert_openapi_to_manual; API docs list OpenApiConverter.convert() instead, which may mislead users copying the snippet.
(Based on your team's feedback about providing accurate, practical implementation examples.)</comment>
<file context>
@@ -0,0 +1,258 @@
+from utcp_http.openapi_converter import OpenApiConverter
+
+converter = OpenApiConverter()
+manual = await converter.convert_openapi_to_manual(
+ "https://api.example.com/openapi.json"
+)
</file context>
| ## Related Protocols | ||
|
|
||
| - [Server-Sent Events](./sse.md) - For streaming HTTP responses | ||
| - [Streamable HTTP](./streamable-http.md) - For chunked HTTP responses |
Contributor
There was a problem hiding this comment.
Link points to a non-existent page (./streamable-http.md), resulting in a broken reference.
(Based on your team's feedback about better navigation and cross-references, ensuring all sidebar links resolve.)
Prompt for AI agents
Address the following comment on docs/providers/http.md at line 257:
<comment>Link points to a non-existent page (./streamable-http.md), resulting in a broken reference.
(Based on your team's feedback about better navigation and cross-references, ensuring all sidebar links resolve.)</comment>
<file context>
@@ -0,0 +1,258 @@
+## Related Protocols
+
+- [Server-Sent Events](./sse.md) - For streaming HTTP responses
+- [Streamable HTTP](./streamable-http.md) - For chunked HTTP responses
+- [WebSocket](./websocket.md) - For bidirectional real-time communication
</file context>
| from utcp.utcp_client import UtcpClient | ||
|
|
||
| # New way - async factory method | ||
| client = await UtcpClient.create(config={ |
Contributor
There was a problem hiding this comment.
await is used at module top level; wrap in an async function (e.g., async def main()) and run it, or restructure the example to avoid top-level awaits.
Prompt for AI agents
Address the following comment on docs/migration-v0.1-to-v1.0.md at line 79:
<comment>await is used at module top level; wrap in an async function (e.g., async def main()) and run it, or restructure the example to avoid top-level awaits.</comment>
<file context>
@@ -0,0 +1,601 @@
+from utcp.utcp_client import UtcpClient
+
+# New way - async factory method
+client = await UtcpClient.create(config={
+ "manual_call_templates": [
+ {
</file context>
| **Solution**: Update manual structure | ||
|
|
||
| ```json | ||
| // Before |
Contributor
There was a problem hiding this comment.
JSON code block contains // comments; either switch the fence to jsonc or remove comments/split into two valid JSON blocks.
Prompt for AI agents
Address the following comment on docs/migration-v0.1-to-v1.0.md at line 518:
<comment>JSON code block contains // comments; either switch the fence to jsonc or remove comments/split into two valid JSON blocks.</comment>
<file context>
@@ -0,0 +1,601 @@
+**Solution**: Update manual structure
+
+```json
+// Before
+{"provider": {"provider_type": "http"}}
+
</file context>
| # Use migration helper | ||
| old_config = load_old_config() | ||
| new_config = migrate_config_v0_to_v1(old_config) | ||
| client = await UtcpClient.create(config=new_config) |
Contributor
There was a problem hiding this comment.
await is used at module top level; wrap in an async function and run it or otherwise avoid top-level awaits in examples.
Prompt for AI agents
Address the following comment on docs/migration-v0.1-to-v1.0.md at line 412:
<comment>await is used at module top level; wrap in an async function and run it or otherwise avoid top-level awaits in examples.</comment>
<file context>
@@ -0,0 +1,601 @@
+# Use migration helper
+old_config = load_old_config()
+new_config = migrate_config_v0_to_v1(old_config)
+client = await UtcpClient.create(config=new_config)
+```
+
</file context>
Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
h3xxit
merged commit 533d73b
into
universal-tool-calling-protocol:enhance-1.0-docs
1 check failed
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The current documentation provides a solid foundation with excellent API references and core concepts. This PR extends that work by adding practical guides and examples that help users implement UTCP more easily.
📋 Enhancements Made
Commit 1: Expand documentation coverage
• ✅ Added protocol-specific guides (HTTP, WebSocket, SSE, CLI, Text, MCP) with practical examples
• ✅ Created implementation guide with step-by-step instructions and multi-language references
• ✅ Added tool provider guide with real-world scenarios
• ✅ Included migration guide to help users transition from v0.1 to v1.0
• ✅ Improved sidebar organization for better navigation
Commit 2: Enhance core documentation pages
• ✅ Expanded landing page with clearer user paths and quick start examples
• ✅ Enhanced security documentation with protocol-specific guidance and code samples
• ✅ Improved UTCP vs MCP comparison with additional technical details and migration options
• ✅ Added consistent language notes to clarify Python examples while noting multi-language support
🚀 Value Added
• Comprehensive protocol coverage with practical implementation examples
• Clear user journeys for different types of implementers
• Enhanced security guidance with actionable best practices
• Migration support for users upgrading between versions
• Better navigation and cross-references throughout
📖 New Documentation Structure
docs/
├── index.md (enhanced with quick start and navigation)
├── for-tool-providers.md (new practical guide)
├── implementation.md (new comprehensive guide)
├── security.md (expanded with protocol-specific guidance)
├── utcp-vs-mcp.md (enhanced with technical details)
├── migration-v0.1-to-v1.0.md (new migration guide)
└── providers/ (new directory with protocol guides)
├── index.md, http.md, websocket.md, sse.md
├── cli.md, text.md, mcp.md
These additions complement the existing excellent API documentation and provide the practical guidance needed for successful UTCP implementations across different use cases and experience levels.
Summary by cubic
Expanded v1.0 docs with protocol guides, implementation and provider manuals, and stronger security and migration content to make UTCP easier to implement and adopt. Reorganized the landing page and sidebar for clearer navigation and faster onboarding.