utcp-gql 1.0.2__tar.gz

utcp_gql-1.0.2/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: utcp-gql
+Version: 1.0.2
+Summary: UTCP communication protocol plugin for GraphQL. (Work in progress)
+Author: UTCP Contributors
+License-Expression: MPL-2.0
+Project-URL: Homepage, https://utcp.io
+Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
+Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: gql>=3.0
+Requires-Dist: utcp>=1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+
+# 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.

utcp_gql-1.0.2/README.md

@@ -0,0 +1,47 @@
+
+# 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.

utcp_gql-1.0.2/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "utcp-gql"
+version = "1.0.2"
+authors = [
+  { name = "UTCP Contributors" },
+]
+description = "UTCP communication protocol plugin for GraphQL. (Work in progress)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+    "gql>=3.0",
+    "utcp>=1.0"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MPL-2.0"
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "coverage",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://utcp.io"
+Source = "https://github.com/universal-tool-calling-protocol/python-utcp"
+Issues = "https://github.com/universal-tool-calling-protocol/python-utcp/issues"

utcp_gql-1.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

utcp_gql-1.0.2/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 GraphQLCallTemplate, GraphQLCallTemplateSerializer
+
+
+def register():
+    register_communication_protocol("graphql", GraphQLCommunicationProtocol())
+    register_call_template("graphql", GraphQLCallTemplateSerializer())

utcp_gql-1.0.2/src/utcp_gql/gql_call_template.py

@@ -0,0 +1,93 @@
+from utcp.data.call_template import CallTemplate
+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, field_serializer, field_validator
+
+class GraphQLCallTemplate(CallTemplate):
+    """Provider configuration for GraphQL-based tools.
+
+    Enables communication with GraphQL endpoints supporting queries, mutations,
+    and subscriptions. Provides flexible query execution with custom headers
+    and authentication.
+
+    For maximum flexibility, use the `query` field to provide a complete GraphQL
+    query string with proper selection sets and variable types. This allows agents
+    to call any existing GraphQL endpoint without limitations.
+
+    Attributes:
+        call_template_type: Always "graphql" for GraphQL providers.
+        url: The GraphQL endpoint URL.
+        operation_type: The type of GraphQL operation (query, mutation, subscription).
+        operation_name: Optional name for the GraphQL operation.
+        auth: Optional authentication configuration.
+        headers: Optional static headers to include in requests.
+        header_fields: List of tool argument names to map to HTTP request headers.
+        query: Custom GraphQL query string with full control over selection sets
+            and variable types. Example: 'query GetUser($id: ID!) { user(id: $id) { id name } }'
+        variable_types: Map of variable names to GraphQL types for auto-generated queries.
+            Example: {'id': 'ID!', 'limit': 'Int'}. Defaults to 'String' if not specified.
+
+    Example:
+        # Full flexibility with custom query
+        template = GraphQLCallTemplate(
+            url="https://api.example.com/graphql",
+            query="query GetUser($id: ID!) { user(id: $id) { id name email } }",
+        )
+
+        # Auto-generation with proper types
+        template = GraphQLCallTemplate(
+            url="https://api.example.com/graphql",
+            variable_types={"limit": "Int", "active": "Boolean"},
+        )
+    """
+
+    call_template_type: Literal["graphql"] = "graphql"
+    url: str
+    operation_type: Literal["query", "mutation", "subscription"] = "query"
+    operation_name: Optional[str] = None
+    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.")
+    query: Optional[str] = Field(
+        default=None,
+        description="Custom GraphQL query/mutation string. Use $varName syntax for variables. "
+                    "If provided, this takes precedence over auto-generation. "
+                    "Example: 'query GetUser($id: ID!) { user(id: $id) { id name email } }'"
+    )
+    variable_types: Optional[Dict[str, str]] = Field(
+        default=None,
+        description="Map of variable names to GraphQL types for auto-generated queries. "
+                    "Example: {'id': 'ID!', 'limit': 'Int', 'active': 'Boolean'}. "
+                    "Defaults to 'String' if not specified."
+    )
+
+    @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 GraphQLCallTemplateSerializer(Serializer[GraphQLCallTemplate]):
+    def to_dict(self, obj: GraphQLCallTemplate) -> dict:
+        return obj.model_dump()
+
+    def validate_dict(self, data: dict) -> GraphQLCallTemplate:
+        try:
+            return GraphQLCallTemplate.model_validate(data)
+        except Exception as e:
+            raise UtcpSerializerValidationError(
+                f"Invalid GraphQLCallTemplate: {e}\n{traceback.format_exc()}"
+            )

utcp_gql-1.0.2/src/utcp_gql/gql_communication_protocol.py

@@ -0,0 +1,229 @@
+import logging
+from typing import Dict, Any, List, Optional, AsyncGenerator, TYPE_CHECKING
+
+import aiohttp
+from gql import Client as GqlClient, gql as gql_query
+from gql.transport.aiohttp import AIOHTTPTransport
+
+from utcp.interfaces.communication_protocol import CommunicationProtocol
+from utcp.data.call_template import CallTemplate
+from utcp.data.tool import Tool, JsonSchema
+from utcp.data.utcp_manual import UtcpManual
+from utcp.data.register_manual_response import RegisterManualResult
+from utcp.data.auth_implementations.api_key_auth import ApiKeyAuth
+from utcp.data.auth_implementations.basic_auth import BasicAuth
+from utcp.data.auth_implementations.oauth2_auth import OAuth2Auth
+
+from utcp_gql.gql_call_template import GraphQLCallTemplate
+
+if TYPE_CHECKING:
+    from utcp.utcp_client import UtcpClient
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(filename)s:%(lineno)d - %(message)s",
+)
+
+logger = logging.getLogger(__name__)
+
+
+class GraphQLCommunicationProtocol(CommunicationProtocol):
+    """GraphQL protocol implementation for UTCP 1.0.
+
+    - Discovers tools via GraphQL schema introspection.
+    - Executes per-call sessions using `gql` over HTTP(S).
+    - Supports `ApiKeyAuth`, `BasicAuth`, and `OAuth2Auth`.
+    - Enforces HTTPS or localhost for security.
+    """
+
+    def __init__(self) -> None:
+        self._oauth_tokens: Dict[str, Dict[str, Any]] = {}
+
+    def _enforce_https_or_localhost(self, url: str) -> None:
+        if not (
+            url.startswith("https://")
+            or url.startswith("http://localhost")
+            or url.startswith("http://127.0.0.1")
+        ):
+            raise ValueError(
+                "Security error: URL must use HTTPS or start with 'http://localhost' or 'http://127.0.0.1'. "
+                "Non-secure URLs are vulnerable to man-in-the-middle attacks. "
+                f"Got: {url}."
+            )
+
+    async def _handle_oauth2(self, auth: OAuth2Auth) -> str:
+        client_id = auth.client_id
+        if client_id in self._oauth_tokens:
+            return self._oauth_tokens[client_id]["access_token"]
+        async with aiohttp.ClientSession() as session:
+            data = {
+                "grant_type": "client_credentials",
+                "client_id": client_id,
+                "client_secret": auth.client_secret,
+                "scope": auth.scope,
+            }
+            async with session.post(auth.token_url, data=data) as resp:
+                resp.raise_for_status()
+                token_response = await resp.json()
+                self._oauth_tokens[client_id] = token_response
+                return token_response["access_token"]
+
+    async def _prepare_headers(
+        self, call_template: GraphQLCallTemplate, tool_args: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, str]:
+        headers: Dict[str, str] = call_template.headers.copy() if call_template.headers else {}
+        if call_template.auth:
+            if isinstance(call_template.auth, ApiKeyAuth):
+                if call_template.auth.api_key and call_template.auth.location == "header":
+                    headers[call_template.auth.var_name] = call_template.auth.api_key
+            elif isinstance(call_template.auth, BasicAuth):
+                import base64
+
+                userpass = f"{call_template.auth.username}:{call_template.auth.password}"
+                headers["Authorization"] = "Basic " + base64.b64encode(userpass.encode()).decode()
+            elif isinstance(call_template.auth, OAuth2Auth):
+                token = await self._handle_oauth2(call_template.auth)
+                headers["Authorization"] = f"Bearer {token}"
+
+        # Map selected tool_args into headers if requested
+        if tool_args and call_template.header_fields:
+            for field in call_template.header_fields:
+                if field in tool_args and isinstance(tool_args[field], str):
+                    headers[field] = tool_args[field]
+
+        return headers
+
+    async def register_manual(
+        self, caller: "UtcpClient", manual_call_template: CallTemplate
+    ) -> RegisterManualResult:
+        if not isinstance(manual_call_template, GraphQLCallTemplate):
+            raise ValueError("GraphQLCommunicationProtocol requires a GraphQLCallTemplate call template")
+        self._enforce_https_or_localhost(manual_call_template.url)
+
+        try:
+            headers = await self._prepare_headers(manual_call_template)
+            transport = AIOHTTPTransport(url=manual_call_template.url, headers=headers)
+            async with GqlClient(transport=transport, fetch_schema_from_transport=True) as session:
+                schema = session.client.schema
+                tools: List[Tool] = []
+
+                # Queries
+                if hasattr(schema, "query_type") and schema.query_type:
+                    for name, field in schema.query_type.fields.items():
+                        tools.append(
+                            Tool(
+                                name=name,
+                                description=getattr(field, "description", "") or "",
+                                inputs=JsonSchema(type="object"),
+                                outputs=JsonSchema(type="object"),
+                                tool_call_template=manual_call_template,
+                            )
+                        )
+
+                # Mutations
+                if hasattr(schema, "mutation_type") and schema.mutation_type:
+                    for name, field in schema.mutation_type.fields.items():
+                        tools.append(
+                            Tool(
+                                name=name,
+                                description=getattr(field, "description", "") or "",
+                                inputs=JsonSchema(type="object"),
+                                outputs=JsonSchema(type="object"),
+                                tool_call_template=manual_call_template,
+                            )
+                        )
+
+                # Subscriptions (listed for completeness)
+                if hasattr(schema, "subscription_type") and schema.subscription_type:
+                    for name, field in schema.subscription_type.fields.items():
+                        tools.append(
+                            Tool(
+                                name=name,
+                                description=getattr(field, "description", "") or "",
+                                inputs=JsonSchema(type="object"),
+                                outputs=JsonSchema(type="object"),
+                                tool_call_template=manual_call_template,
+                            )
+                        )
+
+                manual = UtcpManual(tools=tools)
+                return RegisterManualResult(
+                    manual_call_template=manual_call_template,
+                    manual=manual,
+                    success=True,
+                    errors=[],
+                )
+        except Exception as e:
+            logger.error(f"GraphQL manual registration failed for '{manual_call_template.name}': {e}")
+            return RegisterManualResult(
+                manual_call_template=manual_call_template,
+                manual=UtcpManual(manual_version="0.0.0", tools=[]),
+                success=False,
+                errors=[str(e)],
+            )
+
+    async def deregister_manual(
+        self, caller: "UtcpClient", manual_call_template: CallTemplate
+    ) -> None:
+        # Stateless: nothing to clean up
+        return None
+
+    async def call_tool(
+        self,
+        caller: "UtcpClient",
+        tool_name: str,
+        tool_args: Dict[str, Any],
+        tool_call_template: CallTemplate,
+    ) -> Any:
+        if not isinstance(tool_call_template, GraphQLCallTemplate):
+            raise ValueError("GraphQLCommunicationProtocol requires a GraphQLCallTemplate call template")
+        self._enforce_https_or_localhost(tool_call_template.url)
+
+        headers = await self._prepare_headers(tool_call_template, tool_args)
+        transport = AIOHTTPTransport(url=tool_call_template.url, headers=headers)
+        async with GqlClient(transport=transport, fetch_schema_from_transport=True) as session:
+            # Filter out header fields from GraphQL variables; these are sent via HTTP headers
+            header_fields = tool_call_template.header_fields or []
+            filtered_args = {k: v for k, v in tool_args.items() if k not in header_fields}
+
+            # Use custom query if provided (highest flexibility for agents)
+            if tool_call_template.query:
+                gql_str = tool_call_template.query
+            else:
+                # Auto-generate query - use variable_types for proper typing
+                op_type = getattr(tool_call_template, "operation_type", "query")
+                base_tool_name = tool_name.split(".", 1)[-1] if "." in tool_name else tool_name
+                variable_types = tool_call_template.variable_types or {}
+
+                # Build variable definitions with proper types (default to String)
+                arg_str = ", ".join(
+                    f"${k}: {variable_types.get(k, 'String')}"
+                    for k in filtered_args.keys()
+                )
+                var_defs = f"({arg_str})" if arg_str else ""
+                arg_pass = ", ".join(f"{k}: ${k}" for k in filtered_args.keys())
+                arg_pass = f"({arg_pass})" if arg_pass else ""
+
+                # Note: Auto-generated queries for object-returning fields will still fail
+                # without a selection set. Use the `query` field for full control.
+                gql_str = f"{op_type} {var_defs} {{ {base_tool_name}{arg_pass} }}"
+                logger.debug(f"Auto-generated GraphQL: {gql_str}")
+
+            document = gql_query(gql_str)
+            result = await session.execute(document, variable_values=filtered_args)
+            return result
+
+    async def call_tool_streaming(
+        self,
+        caller: "UtcpClient",
+        tool_name: str,
+        tool_args: Dict[str, Any],
+        tool_call_template: CallTemplate,
+    ) -> AsyncGenerator[Any, None]:
+        # Basic implementation: execute non-streaming and yield once
+        result = await self.call_tool(caller, tool_name, tool_args, tool_call_template)
+        yield result
+
+    async def close(self) -> None:
+        self._oauth_tokens.clear()

utcp_gql-1.0.2/src/utcp_gql.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: utcp-gql
+Version: 1.0.2
+Summary: UTCP communication protocol plugin for GraphQL. (Work in progress)
+Author: UTCP Contributors
+License-Expression: MPL-2.0
+Project-URL: Homepage, https://utcp.io
+Project-URL: Source, https://github.com/universal-tool-calling-protocol/python-utcp
+Project-URL: Issues, https://github.com/universal-tool-calling-protocol/python-utcp/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: gql>=3.0
+Requires-Dist: utcp>=1.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+
+# 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.

utcp_gql-1.0.2/src/utcp_gql.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/utcp_gql/__init__.py
+src/utcp_gql/gql_call_template.py
+src/utcp_gql/gql_communication_protocol.py
+src/utcp_gql.egg-info/PKG-INFO
+src/utcp_gql.egg-info/SOURCES.txt
+src/utcp_gql.egg-info/dependency_links.txt
+src/utcp_gql.egg-info/requires.txt
+src/utcp_gql.egg-info/top_level.txt
+tests/test_graphql_integration.py

utcp_gql-1.0.2/src/utcp_gql.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

utcp_gql-1.0.2/src/utcp_gql.egg-info/requires.txt

@@ -0,0 +1,11 @@
+pydantic>=2.0
+gql>=3.0
+utcp>=1.0
+
+[dev]
+build
+pytest
+pytest-asyncio
+pytest-cov
+coverage
+twine

utcp_gql-1.0.2/src/utcp_gql.egg-info/top_level.txt

@@ -0,0 +1 @@
+utcp_gql

utcp_gql-1.0.2/tests/test_graphql_integration.py

@@ -0,0 +1,275 @@
+"""Integration tests for GraphQL communication protocol using real GraphQL servers.
+
+Uses the public Countries API (https://countries.trevorblades.com/graphql) which
+requires no authentication and has a stable schema.
+"""
+import os
+import sys
+import warnings
+import pytest
+import pytest_asyncio
+
+# Ensure plugin src is importable
+PLUGIN_SRC = os.path.join(os.path.dirname(__file__), "..", "src")
+PLUGIN_SRC = os.path.abspath(PLUGIN_SRC)
+if PLUGIN_SRC not in sys.path:
+    sys.path.append(PLUGIN_SRC)
+
+import utcp_gql
+from utcp_gql.gql_call_template import GraphQLCallTemplate
+from utcp_gql.gql_communication_protocol import GraphQLCommunicationProtocol
+
+from utcp.implementations.utcp_client_implementation import UtcpClientImplementation
+
+# Public GraphQL API for testing (no auth required)
+COUNTRIES_API_URL = "https://countries.trevorblades.com/graphql"
+
+# Suppress gql SSL warning (we're using HTTPS which is secure)
+warnings.filterwarnings("ignore", message=".*AIOHTTPTransport does not verify ssl.*")
+
+
+@pytest.fixture
+def protocol():
+    """Create a fresh GraphQL protocol instance."""
+    utcp_gql.register()
+    return GraphQLCommunicationProtocol()
+
+
+@pytest_asyncio.fixture
+async def client():
+    """Create a minimal UTCP client."""
+    return await UtcpClientImplementation.create()
+
+
+@pytest.mark.asyncio
+async def test_register_manual_discovers_tools(protocol, client):
+    """Test that register_manual discovers tools from a real GraphQL schema."""
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+    )
+
+    result = await protocol.register_manual(client, template)
+
+    assert result.success is True
+    assert len(result.manual.tools) > 0
+
+    # The Countries API should have these common queries
+    tool_names = [t.name for t in result.manual.tools]
+    assert "countries" in tool_names or "country" in tool_names
+
+
+@pytest.mark.asyncio
+async def test_call_tool_with_custom_query(protocol, client):
+    """Test calling a tool with a custom query string (fixes selection set issue)."""
+    # Custom query with proper selection set - this is the UTCP-flexible approach
+    custom_query = """
+    query GetCountry($code: ID!) {
+        country(code: $code) {
+            name
+            capital
+            currency
+        }
+    }
+    """
+
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+        query=custom_query,
+    )
+
+    result = await protocol.call_tool(
+        client,
+        "country",
+        {"code": "US"},
+        template,
+    )
+
+    assert result is not None
+    assert "country" in result
+    assert result["country"]["name"] == "United States"
+    assert result["country"]["capital"] == "Washington D.C."
+
+
+@pytest.mark.asyncio
+async def test_call_tool_with_variable_types(protocol, client):
+    """Test that variable_types properly maps GraphQL types (fixes String-only issue)."""
+    # The country query expects code: ID!, not String
+    # Using variable_types to specify the correct type
+    custom_query = """
+    query GetCountry($code: ID!) {
+        country(code: $code) {
+            name
+            emoji
+        }
+    }
+    """
+
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+        query=custom_query,
+        variable_types={"code": "ID!"},
+    )
+
+    result = await protocol.call_tool(
+        client,
+        "country",
+        {"code": "FR"},
+        template,
+    )
+
+    assert result is not None
+    assert result["country"]["name"] == "France"
+    assert result["country"]["emoji"] == "🇫🇷"
+
+
+@pytest.mark.asyncio
+async def test_call_tool_list_query(protocol, client):
+    """Test querying a list of items with proper selection set."""
+    custom_query = """
+    query GetContinents {
+        continents {
+            code
+            name
+        }
+    }
+    """
+
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+        query=custom_query,
+    )
+
+    result = await protocol.call_tool(
+        client,
+        "continents",
+        {},
+        template,
+    )
+
+    assert result is not None
+    assert "continents" in result
+    assert len(result["continents"]) == 7  # 7 continents
+
+    continent_names = [c["name"] for c in result["continents"]]
+    assert "Europe" in continent_names
+    assert "Asia" in continent_names
+
+
+@pytest.mark.asyncio
+async def test_call_tool_nested_query(protocol, client):
+    """Test querying nested objects with proper selection sets."""
+    custom_query = """
+    query GetCountryWithLanguages($code: ID!) {
+        country(code: $code) {
+            name
+            languages {
+                code
+                name
+            }
+        }
+    }
+    """
+
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+        query=custom_query,
+    )
+
+    result = await protocol.call_tool(
+        client,
+        "country",
+        {"code": "CH"},  # Switzerland - has multiple languages
+        template,
+    )
+
+    assert result is not None
+    assert result["country"]["name"] == "Switzerland"
+    assert len(result["country"]["languages"]) >= 3  # German, French, Italian, Romansh
+
+
+@pytest.mark.asyncio
+async def test_call_tool_with_filter_arguments(protocol, client):
+    """Test queries with filter arguments using proper types."""
+    custom_query = """
+    query GetCountriesByContinent($filter: CountryFilterInput) {
+        countries(filter: $filter) {
+            code
+            name
+        }
+    }
+    """
+
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+        query=custom_query,
+        variable_types={"filter": "CountryFilterInput"},
+    )
+
+    result = await protocol.call_tool(
+        client,
+        "countries",
+        {"filter": {"continent": {"eq": "EU"}}},
+        template,
+    )
+
+    assert result is not None
+    assert "countries" in result
+    # Should return European countries
+    country_codes = [c["code"] for c in result["countries"]]
+    assert "DE" in country_codes  # Germany
+    assert "FR" in country_codes  # France
+
+
+@pytest.mark.asyncio
+async def test_error_handling_invalid_query(protocol, client):
+    """Test that invalid queries return proper errors."""
+    # Invalid query syntax
+    invalid_query = "this is not valid graphql"
+
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+        query=invalid_query,
+    )
+
+    with pytest.raises(Exception):
+        await protocol.call_tool(
+            client,
+            "invalid",
+            {},
+            template,
+        )
+
+
+@pytest.mark.asyncio
+async def test_error_handling_missing_selection_set_auto_generated(protocol, client):
+    """
+    Demonstrate that auto-generated queries fail for object-returning fields.
+    
+    This test documents the limitation: without a custom query, object fields fail.
+    The fix is to always use the `query` field for object-returning operations.
+    """
+    # No custom query - will auto-generate without selection set
+    template = GraphQLCallTemplate(
+        name="countries_api",
+        url=COUNTRIES_API_URL,
+        operation_type="query",
+        variable_types={"code": "ID!"},
+    )
+
+    # This should fail because auto-generated query lacks selection set
+    # The query becomes: query ($code: ID!) { country(code: $code) }
+    # But country returns an object that needs: { name capital ... }
+    with pytest.raises(Exception):
+        await protocol.call_tool(
+            client,
+            "country",
+            {"code": "US"},
+            template,
+        )