GraphQL Plugin: UTCP 1.0 Migration

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.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()}"
+            )