📚 Enhance v1.0 Documentation: Add Protocol Guides, Implementation Exa… #46
+10,979
−771
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
…mples, and User Navigation (#43) * chore: update contributors data 2025-09-04 * chore: update contributors data 2025-09-04 * chore: update contributors data 2025-09-05 * Add comprehensive v1.0 documentation - 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 * 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 * Update docs/index.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Add missing API documentation for core classes - Add class descriptions for UtcpClient, serializers, and auth implementations - Add documentation for tool repository and variable loader classes - Add call template documentation for HTTP, CLI, Text, and SSE protocols - Fix 'No class documentation available' entries with minimal descriptions * Fix providers/index.md ID for sidebar compatibility * Revert "Add missing API documentation for core classes" This reverts commit 2eb1439. * Update terminology from providers to protocol plugins - Rename docs/providers to docs/protocols for v1.0 terminology - Update sidebars.ts to reference protocols/ paths - Update protocols/index.md with correct plugin-based architecture description - Replace 'providers' with 'protocol plugins' throughout documentation - Align with v1.0 call template terminology * Phase 1: Make protocol documentation language-independent - Remove Python-specific examples from specification protocols - Replace with JSON/YAML configuration examples - Add references to language-specific documentation - Keep protocol concepts and architecture language-agnostic * Continue Phase 1: Remove Python dependencies from core docs - Replace implementation.md with language-independent version - Remove Python examples from index.md quick start - Replace with JSON configuration and conceptual descriptions - Add references to language-specific documentation * Complete Phase 1: Remove final Python dependencies - Replace remaining Python example in for-tool-providers.md - All core documentation now language-independent - Python-specific examples moved to python-utcp repository - JSON/YAML configuration examples throughout * Remove Python language bias from documentation - Remove Python-specific language from intro sections - Make language references neutral in index.md and for-tool-providers.md - Keep Python examples in CLI/MCP protocols as they're just examples - Update links to be language-neutral * Start removing Python code from security.md while preserving JSON - Remove Python language bias from intro - Replace Python implementation examples with language-independent guidance - Keep all JSON configuration examples - Preserve security concepts and best practices * Continue removing Python code from security.md - Replace path validation Python example with requirements - Preserve JSON configuration examples - Keep security concepts language-independent * Remove Python language bias from specification - Convert Python code examples to language-agnostic descriptions - Replace Python-specific documentation links with multi-language references - Maintain technical accuracy while ensuring language neutrality - Major files updated: utcp-vs-mcp.md, migration-v0.1-to-v1.0.md - Updated documentation links across all protocol files * Remove UTCP specification field requirements from documentation - Remove field requirement tables (Required/Optional Fields) from protocol docs - Remove UTCP manual structure requirement tables from tool provider guide - Replace with references to API specification documentation - Keep API input/output schema examples as they describe tool interfaces - Eliminates duplication between user docs and API specification * Remove Express.js implementation section - Remove technology-specific implementation example - Keep language-agnostic conceptual guidance - Maintain focus on UTCP concepts rather than specific frameworks * Updated API spec * Update docs * Update 1.0 versioned docs --------- Co-authored-by: GitHub Action <[email protected]> Co-authored-by: Luca Perrozzi <[email protected]> Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
| converter = OpenApiConverter() | ||
|
|
||
|
|
||
| **With Open("Api_Spec.Yaml", "R") As F** |
Contributor
There was a problem hiding this comment.
This line is not valid Python (looks like VB-style pseudocode) and breaks the example; replace with a proper Python with open(...) context manager.
Prompt for AI agents
Address the following comment on docs/api/plugins/communication_protocols/http/src/utcp_http/openapi_converter.md at line 62:
<comment>This line is not valid Python (looks like VB-style pseudocode) and breaks the example; replace with a proper Python with open(...) context manager.</comment>
<file context>
@@ -22,14 +22,50 @@ a UTCP tool with appropriate input/output schemas.
+ converter = OpenApiConverter()
+
+
+**With Open("Api_Spec.Yaml", "R") As F**
+
+spec_content = yaml.safe_load(f)
</file context>
| "call_template_type": "http", | ||
| "url": "http://localhost:8000/weather", | ||
| "http_method": "GET" | ||
| } |
Contributor
There was a problem hiding this comment.
Invalid JSON example due to extra closing braces/brackets; readers copying this will encounter parse errors.
Prompt for AI agents
Address the following comment on docs/index.md at line 67:
<comment>Invalid JSON example due to extra closing braces/brackets; readers copying this will encounter parse errors.</comment>
<file context>
@@ -4,152 +4,219 @@ title: Introduction
+ "call_template_type": "http",
+ "url": "http://localhost:8000/weather",
+ "http_method": "GET"
+ }
+ }],
+ "auth": {
</file context>
| ```json | ||
| { | ||
| "call_template_type": "mcp", | ||
| "server_config": { |
Contributor
There was a problem hiding this comment.
MCP call template uses non-spec key server_config; should use config.mcpServers per plugin API
Prompt for AI agents
Address the following comment on docs/protocols/mcp.md at line 16:
<comment>MCP call template uses non-spec key server_config; should use config.mcpServers per plugin API</comment>
<file context>
@@ -0,0 +1,266 @@
+```json
+{
+ "call_template_type": "mcp",
+ "server_config": {
+ "command": "node",
+ "args": ["mcp-server.js"],
</file context>
| }, | ||
| "timeout": 60, | ||
| "max_events": 10, | ||
| "event_filter": { |
Contributor
There was a problem hiding this comment.
Documentation introduces unsupported field event_filter; use event_type per SSE Call Template spec or update spec if event_filter is intended.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/protocols/sse.md at line 35:
<comment>Documentation introduces unsupported field event_filter; use event_type per SSE Call Template spec or update spec if event_filter is intended.</comment>
<file context>
@@ -0,0 +1,386 @@
+ },
+ "timeout": 60,
+ "max_events": 10,
+ "event_filter": {
+ "type": "data_update"
+ }
</file context>
| "var_name": "Authorization", | ||
| "location": "header" | ||
| }, | ||
| "body_field": "user_data" |
Contributor
There was a problem hiding this comment.
The call template references body_field "user_data" that isn’t defined in inputs; align body_field with defined inputs or change the inputs/body accordingly.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/for-tool-providers.md at line 361:
<comment>The call template references body_field "user_data" that isn’t defined in inputs; align body_field with defined inputs or change the inputs/body accordingly.</comment>
<file context>
@@ -0,0 +1,580 @@
+ "var_name": "Authorization",
+ "location": "header"
+ },
+ "body_field": "user_data"
+ }
+ }
</file context>
| "type": "object", | ||
| "properties": { | ||
| "location": {"type": "string"} | ||
| } |
Contributor
There was a problem hiding this comment.
Redundant closing brace leads to malformed JSON in the example; one of these '}' should be removed.
Prompt for AI agents
Address the following comment on docs/migration-v0.1-to-v1.0.md at line 125:
<comment>Redundant closing brace leads to malformed JSON in the example; one of these '}' should be removed.</comment>
<file context>
@@ -0,0 +1,465 @@
+ "type": "object",
+ "properties": {
+ "location": {"type": "string"}
+ }
+ },
+ "provider": {
</file context>
| - **Contains:** 2 classes | ||
|
|
||
|
|
||
| ### [utcp.implementations.post_processors.limit_strings_post_processor](./core\utcp\implementations\post_processors\limit_strings_post_processor.md) |
Contributor
There was a problem hiding this comment.
Link target uses backslashes; use forward slashes to avoid broken URLs in the built docs.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/api/index.md at line 101:
<comment>Link target uses backslashes; use forward slashes to avoid broken URLs in the built docs.</comment>
<file context>
@@ -93,6 +93,16 @@ Core UTCP framework components that define the fundamental interfaces and implem
+- **Contains:** 2 classes
+
+
+### [utcp.implementations.post_processors.limit_strings_post_processor](./core\utcp\implementations\post_processors\limit_strings_post_processor.md)
+
+- **Contains:** 2 classes
</file context>
Suggested change
| ### [utcp.implementations.post_processors.limit_strings_post_processor](./core\utcp\implementations\post_processors\limit_strings_post_processor.md) | |
| ### [utcp.implementations.post_processors.limit_strings_post_processor](./core/utcp/implementations/post_processors/limit_strings_post_processor.md) |
| - **Contains:** 2 classes, 12 methods | ||
|
|
||
|
|
||
| ### [utcp.implementations.post_processors.filter_dict_post_processor](./core\utcp\implementations\post_processors\filter_dict_post_processor.md) |
Contributor
There was a problem hiding this comment.
Link target uses backslashes; use forward slashes to avoid broken URLs in the built docs.
Prompt for AI agents
Address the following comment on versioned_docs/version-1.0/api/index.md at line 96:
<comment>Link target uses backslashes; use forward slashes to avoid broken URLs in the built docs.</comment>
<file context>
@@ -93,6 +93,16 @@ Core UTCP framework components that define the fundamental interfaces and implem
- **Contains:** 2 classes, 12 methods
+### [utcp.implementations.post_processors.filter_dict_post_processor](./core\utcp\implementations\post_processors\filter_dict_post_processor.md)
+
+- **Contains:** 2 classes
</file context>
Suggested change
| ### [utcp.implementations.post_processors.filter_dict_post_processor](./core\utcp\implementations\post_processors\filter_dict_post_processor.md) | |
| ### [utcp.implementations.post_processors.filter_dict_post_processor](./core/utcp/implementations/post_processors/filter_dict_post_processor.md) |
|
|
||
| ```json | ||
| { | ||
| "max_size": 1048576 // 1MB limit |
Contributor
There was a problem hiding this comment.
JSON code block includes // comment; remove it for valid JSON.
Prompt for AI agents
Address the following comment on docs/protocols/text.md at line 318:
<comment>JSON code block includes // comment; remove it for valid JSON.</comment>
<file context>
@@ -0,0 +1,437 @@
+
+```json
+{
+ "max_size": 1048576 // 1MB limit
+}
+```
</file context>
|
|
||
| ```json | ||
| { | ||
| "transform": "normalize_whitespace" // Normalize all whitespace |
Contributor
There was a problem hiding this comment.
JSON code block includes // comment; remove it for valid JSON.
Prompt for AI agents
Address the following comment on docs/protocols/text.md at line 256:
<comment>JSON code block includes // comment; remove it for valid JSON.</comment>
<file context>
@@ -0,0 +1,437 @@
+
+```json
+{
+ "transform": "normalize_whitespace" // Normalize all whitespace
+}
+```
</file context>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
…mples, and User Navigation (#43)
chore: update contributors data 2025-09-04
chore: update contributors data 2025-09-04
chore: update contributors data 2025-09-05
Add comprehensive v1.0 documentation
Update docs/index.md
Add missing API documentation for core classes
Fix providers/index.md ID for sidebar compatibility
Revert "Add missing API documentation for core classes"
This reverts commit 2eb1439.
Updated API spec
Update docs
Update 1.0 versioned docs
Summary by cubic
Overhauled UTCP v1.0 docs with complete protocol guides, a clear implementation path, and improved navigation to close gaps in the current version. Adds a migration guide and expands API references to make adoption easier.
New Features
Refactors