GraphQL Plugin: UTCP 1.0 Migration

.github/workflows/test.yml

@@ -31,10 +31,11 @@ jobs:
         pip install -e plugins/communication_protocols/http[dev]
         pip install -e plugins/communication_protocols/mcp[dev]
         pip install -e plugins/communication_protocols/text[dev]
+        pip install -e plugins/communication_protocols/socket[dev]
 
     - name: Run tests with pytest
       run: |
-        pytest core/tests/ plugins/communication_protocols/cli/tests/ plugins/communication_protocols/http/tests/ plugins/communication_protocols/mcp/tests/ plugins/communication_protocols/text/tests/ --doctest-modules --junitxml=junit/test-results.xml --cov=core/src/utcp --cov-report=xml --cov-report=html
+        pytest core/tests/ plugins/communication_protocols/cli/tests/ plugins/communication_protocols/http/tests/ plugins/communication_protocols/mcp/tests/ plugins/communication_protocols/text/tests/ plugins/communication_protocols/socket/tests/ --doctest-modules --junitxml=junit/test-results.xml --cov=core/src/utcp --cov-report=xml --cov-report=html
 
     - name: Upload coverage reports to Codecov
       uses: codecov/codecov-action@v3

plugins/communication_protocols/gql/README.md

@@ -1 +1,47 @@
-Find the UTCP readme at https://github.com/universal-tool-calling-protocol/python-utcp.
+
+UTCP GraphQL Communication Protocol Plugin
+
+This plugin integrates GraphQL as a UTCP 1.0 communication protocol and call template. It supports discovery via schema introspection, authenticated calls, and header handling.
+
+Getting Started
+
+Installation
+
+```bash
+pip install gql
+```
+
+Registration
+
+```python
+import utcp_gql
+utcp_gql.register()
+```
+
+How To Use
+
+- Ensure the plugin is imported and registered: `import utcp_gql; utcp_gql.register()`.
+- Add a manual in your client config:
+  ```json
+  {
+    "name": "my_graph",
+    "call_template_type": "graphql",
+    "url": "https://your.graphql/endpoint",
+    "operation_type": "query",
+    "headers": { "x-client": "utcp" },
+    "header_fields": ["x-session-id"]
+  }
+  ```
+- Call a tool:
+  ```python
+  await client.call_tool("my_graph.someQuery", {"id": "123", "x-session-id": "abc"})
+  ```
+
+Notes
+
+- Tool names are prefixed by the manual name (e.g., `my_graph.someQuery`).
+- Headers merge static `headers` plus whitelisted dynamic fields from `header_fields`.
+- Supported auth: API key, Basic auth, OAuth2 (client-credentials).
+- Security: only `https://` or `http://localhost`/`http://127.0.0.1` endpoints.
+
+For UTCP core docs, see https://github.com/universal-tool-calling-protocol/python-utcp.

plugins/communication_protocols/gql/src/utcp_gql/__init__.py

@@ -0,0 +1,9 @@
+from utcp.plugins.discovery import register_communication_protocol, register_call_template
+
+from .gql_communication_protocol import GraphQLCommunicationProtocol
+from .gql_call_template import GraphQLProvider, GraphQLProviderSerializer
+
+
+def register():
+    register_communication_protocol("graphql", GraphQLCommunicationProtocol())
+    register_call_template("graphql", GraphQLProviderSerializer())

plugins/communication_protocols/gql/src/utcp_gql/gql_call_template.py

@@ -1,7 +1,10 @@
-from utcp.data.call_template import CallTemplate
-from utcp.data.auth import Auth
+from utcp.data.call_template import CallTemplate, CallTemplateSerializer
+from utcp.data.auth import Auth, AuthSerializer
+from utcp.interfaces.serializer import Serializer
+from utcp.exceptions import UtcpSerializerValidationError
+import traceback
 from typing import Dict, List, Optional, Literal
-from pydantic import Field
+from pydantic import Field, field_serializer, field_validator
 
 class GraphQLProvider(CallTemplate):
     """Provider configuration for GraphQL-based tools.
@@ -27,3 +30,31 @@ class GraphQLProvider(CallTemplate):
     auth: Optional[Auth] = None
     headers: Optional[Dict[str, str]] = None
     header_fields: Optional[List[str]] = Field(default=None, description="List of input fields to be sent as request headers for the initial connection.")
+
+    @field_serializer("auth")
+    def serialize_auth(self, auth: Optional[Auth]):
+        if auth is None:
+            return None
+        return AuthSerializer().to_dict(auth)
+
+    @field_validator("auth", mode="before")
+    @classmethod
+    def validate_auth(cls, v: Optional[Auth | dict]):
+        if v is None:
+            return None
+        if isinstance(v, Auth):
+            return v
+        return AuthSerializer().validate_dict(v)
+
+
+class GraphQLProviderSerializer(Serializer[GraphQLProvider]):
+    def to_dict(self, obj: GraphQLProvider) -> dict:
+        return obj.model_dump()
+
+    def validate_dict(self, data: dict) -> GraphQLProvider:
+        try:
+            return GraphQLProvider.model_validate(data)
+        except Exception as e:
+            raise UtcpSerializerValidationError(
+                f"Invalid GraphQLProvider: {e}\n{traceback.format_exc()}"
+            )