graphql-mcp 1.0.0__tar.gz

graphql_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Robert Parker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphql_mcp-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include VERSION

graphql_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: graphql_mcp
+Version: 1.0.0
+Summary: A framework for building Python GraphQL MCP servers.
+Home-page: https://gitlab.com/parob/graphql-mcp
+Download-URL: https://gitlab.com/parob/graphql-mcp/-/archive/v1.0.0/graphql_mcp-v1.0.0.tar.gz
+Author: Robert Parker
+Author-email: rob@parob.com
+License: MIT
+Keywords: GraphQL,GraphQL-API,GraphQLAPI,Server,MCP,Multi-Model-Protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphql-core~=3.1
+Requires-Dist: fastmcp~=2.9
+Requires-Dist: graphql-api>=1.3.0
+Provides-Extra: dev
+Requires-Dist: graphql-api>=1.3.0; extra == "dev"
+Requires-Dist: pytest~=5.4; extra == "dev"
+Requires-Dist: pytest-cov~=2.10; extra == "dev"
+Requires-Dist: coverage~=5.2; extra == "dev"
+Requires-Dist: faker~=4.1; extra == "dev"
+Requires-Dist: fastmcp~=2.9; extra == "dev"
+Requires-Dist: pytest-asyncio~=0.18; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+# graphql-mcp

graphql_mcp-1.0.0/README.md

@@ -0,0 +1 @@
+# graphql-mcp

graphql_mcp-1.0.0/VERSION

@@ -0,0 +1 @@
+1.0.0

graphql_mcp-1.0.0/graphql_mcp/server.py

@@ -0,0 +1,270 @@
+import enum
+import inspect
+import re
+import uuid
+import json
+
+from datetime import date, datetime
+from typing import Any, Callable
+
+from fastmcp import FastMCP
+
+from graphql import (
+    GraphQLArgument,
+    GraphQLEnumType,
+    GraphQLField,
+    GraphQLInputObjectType,
+    GraphQLList,
+    GraphQLNonNull,
+    GraphQLSchema,
+    GraphQLString,
+    GraphQLInt,
+    GraphQLFloat,
+    GraphQLBoolean,
+    GraphQLID,
+    get_named_type,
+    graphql_sync,
+    is_leaf_type,
+)
+
+try:
+    from graphql_api.types import (
+        GraphQLUUID,
+        GraphQLDateTime,
+        GraphQLDate,
+        GraphQLJSON,
+        GraphQLBytes,
+    )
+
+    HAS_GRAPHQL_API = True
+except ImportError:
+    HAS_GRAPHQL_API = False
+    GraphQLUUID = object()
+    GraphQLDateTime = object()
+    GraphQLDate = object()
+    GraphQLJSON = object()
+    GraphQLBytes = object()
+
+
+def _map_graphql_type_to_python_type(graphql_type: Any) -> Any:
+    """
+    Maps a GraphQL type to a Python type for function signatures.
+    """
+    if isinstance(graphql_type, GraphQLNonNull):
+        return _map_graphql_type_to_python_type(graphql_type.of_type)
+    if isinstance(graphql_type, GraphQLList):
+        return list[_map_graphql_type_to_python_type(graphql_type.of_type)]
+
+    # Scalar types
+    if graphql_type is GraphQLString:
+        return str
+    if graphql_type is GraphQLInt:
+        return int
+    if graphql_type is GraphQLFloat:
+        return float
+    if graphql_type is GraphQLBoolean:
+        return bool
+    if graphql_type is GraphQLID:
+        return str
+
+    if HAS_GRAPHQL_API:
+        if graphql_type is GraphQLUUID:
+            return uuid.UUID
+        if graphql_type is GraphQLDateTime:
+            return datetime
+        if graphql_type is GraphQLDate:
+            return date
+        if graphql_type is GraphQLJSON:
+            return Any
+        if graphql_type is GraphQLBytes:
+            return bytes
+
+    if isinstance(graphql_type, GraphQLEnumType):
+        # Create a Python enum from the GraphQL enum
+        return enum.Enum(
+            graphql_type.name,
+            {k: v.value for k, v in graphql_type.values.items()},
+        )
+
+    if isinstance(graphql_type, GraphQLInputObjectType):
+        # This is complex. For now, we'll treat it as a dict.
+        # fastmcp can handle pydantic models or dataclasses.
+        # We might need to generate them on the fly.
+        return dict
+
+    return Any
+
+
+def _to_snake_case(name: str) -> str:
+    """Converts a camelCase string to snake_case."""
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+def _get_graphql_type_name(graphql_type: Any) -> str:
+    """
+    Gets the name of a GraphQL type for use in a query string.
+    """
+    if isinstance(graphql_type, GraphQLNonNull):
+        return f"{_get_graphql_type_name(graphql_type.of_type)}!"
+    if isinstance(graphql_type, GraphQLList):
+        return f"[{_get_graphql_type_name(graphql_type.of_type)}]"
+    return graphql_type.name
+
+
+def _build_selection_set(graphql_type: Any, max_depth: int = 2, depth: int = 0) -> str:
+    """
+    Builds a selection set for a GraphQL type.
+    Only includes scalar fields.
+    """
+    if depth >= max_depth:
+        return ""
+
+    named_type = get_named_type(graphql_type)
+    if is_leaf_type(named_type):
+        return ""
+
+    selections = []
+    if hasattr(named_type, "fields"):
+        for field_name, field_def in named_type.fields.items():
+            field_named_type = get_named_type(field_def.type)
+            if is_leaf_type(field_named_type):
+                selections.append(field_name)
+            else:
+                nested_selection = _build_selection_set(
+                    field_def.type, max_depth=max_depth, depth=depth + 1
+                )
+                if nested_selection:
+                    selections.append(f"{field_name} {nested_selection}")
+
+    if not selections:
+        # If no leaf fields, maybe it's an object with no scalar fields.
+        # What to do here? Can't return an empty object.
+        # Maybe just return __typename as a default.
+        return "{ __typename }"
+
+    return f"{{ {', '.join(selections)} }}"
+
+
+def _add_tools_from_fields(
+    server: FastMCP,
+    schema: GraphQLSchema,
+    fields: dict[str, Any],
+    is_mutation: bool,
+):
+    """Internal helper to add tools from a dictionary of fields."""
+    for field_name, field in fields.items():
+        snake_case_name = _to_snake_case(field_name)
+        tool_func = _create_tool_function(
+            field_name, field, schema, is_mutation=is_mutation
+        )
+        tool_decorator = server.tool(name=snake_case_name)
+        tool_decorator(tool_func)
+
+
+async def add_query_tools_from_schema(server: FastMCP, schema: GraphQLSchema):
+    """Adds tools to a FastMCP server from the query fields of a GraphQL schema."""
+    if schema.query_type:
+        _add_tools_from_fields(
+            server, schema, schema.query_type.fields, is_mutation=False
+        )
+
+
+async def add_mutation_tools_from_schema(server: FastMCP, schema: GraphQLSchema):
+    """Adds tools to a FastMCP server from the mutation fields of a GraphQL schema."""
+    if schema.mutation_type:
+        _add_tools_from_fields(
+            server, schema, schema.mutation_type.fields, is_mutation=True
+        )
+
+
+async def from_graphql_schema(
+    schema: GraphQLSchema, server: FastMCP | None = None
+) -> FastMCP:
+    """
+    Populates a FastMCP server with tools generated from a GraphQLSchema.
+
+    If a server instance is not provided, a new one will be created.
+    Processes mutations first, then queries, so that queries will overwrite
+    any mutations with the same name.
+
+    :param schema: The GraphQLSchema to map.
+    :param server: An optional existing FastMCP server instance to add tools to.
+    :return: The populated FastMCP server instance.
+    """
+    if server is None:
+        server = FastMCP(name=schema.description or "GraphQL Server")
+
+    # Process mutations first, so that queries can overwrite them if a name collision occurs.
+    await add_mutation_tools_from_schema(server, schema)
+    await add_query_tools_from_schema(server, schema)
+
+    return server
+
+
+def _create_tool_function(
+    field_name: str,
+    field: GraphQLField,
+    schema: GraphQLSchema,
+    is_mutation: bool = False,
+) -> Callable:
+    """
+    Creates a function that can be decorated as a fastmcp tool.
+    """
+    parameters = []
+    arg_defs = []
+    annotations = {}
+    for arg_name, arg_def in field.args.items():
+        arg_def: GraphQLArgument
+        python_type = _map_graphql_type_to_python_type(arg_def.type)
+        annotations[arg_name] = python_type
+        default = (
+            arg_def.default_value
+            if arg_def.default_value is not inspect.Parameter.empty
+            else inspect.Parameter.empty
+        )
+        kind = inspect.Parameter.POSITIONAL_OR_KEYWORD
+        parameters.append(
+            inspect.Parameter(arg_name, kind, default=default, annotation=python_type)
+        )
+        arg_defs.append(f"${arg_name}: {_get_graphql_type_name(arg_def.type)}")
+
+    def wrapper(**kwargs):
+        # Convert enums to their values for graphql_sync
+        processed_kwargs = {}
+        for k, v in kwargs.items():
+            if isinstance(v, enum.Enum):
+                processed_kwargs[k] = v.value
+            elif hasattr(v, "model_dump"):  # Check for Pydantic model
+                processed_kwargs[k] = v.model_dump(mode="json")
+            elif isinstance(v, dict):
+                # graphql-api expects a JSON string for dict inputs
+                processed_kwargs[k] = json.dumps(v)
+            else:
+                processed_kwargs[k] = v
+
+        operation_type = "mutation" if is_mutation else "query"
+        arg_str = ", ".join(f"{name}: ${name}" for name in kwargs)
+        selection_set = _build_selection_set(field.type)
+
+        query_str = f"{operation_type} ({', '.join(arg_defs)}) {{ {field_name}({arg_str}) {selection_set} }}"
+        if not arg_defs:
+            query_str = f"{operation_type} {{ {field_name} {selection_set} }}"
+
+        # Execute the query
+        result = graphql_sync(schema, query_str, variable_values=processed_kwargs)
+
+        if result.errors:
+            # For simplicity, just raise the first error
+            raise result.errors[0]
+
+        if result.data:
+            return result.data.get(field_name)
+
+        return None
+
+    wrapper.__signature__ = inspect.Signature(parameters)
+    wrapper.__doc__ = field.description
+    wrapper.__name__ = _to_snake_case(field_name)
+    wrapper.__annotations__ = annotations
+
+    return wrapper

graphql_mcp-1.0.0/graphql_mcp.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: graphql_mcp
+Version: 1.0.0
+Summary: A framework for building Python GraphQL MCP servers.
+Home-page: https://gitlab.com/parob/graphql-mcp
+Download-URL: https://gitlab.com/parob/graphql-mcp/-/archive/v1.0.0/graphql_mcp-v1.0.0.tar.gz
+Author: Robert Parker
+Author-email: rob@parob.com
+License: MIT
+Keywords: GraphQL,GraphQL-API,GraphQLAPI,Server,MCP,Multi-Model-Protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphql-core~=3.1
+Requires-Dist: fastmcp~=2.9
+Requires-Dist: graphql-api>=1.3.0
+Provides-Extra: dev
+Requires-Dist: graphql-api>=1.3.0; extra == "dev"
+Requires-Dist: pytest~=5.4; extra == "dev"
+Requires-Dist: pytest-cov~=2.10; extra == "dev"
+Requires-Dist: coverage~=5.2; extra == "dev"
+Requires-Dist: faker~=4.1; extra == "dev"
+Requires-Dist: fastmcp~=2.9; extra == "dev"
+Requires-Dist: pytest-asyncio~=0.18; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+# graphql-mcp

graphql_mcp-1.0.0/graphql_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+VERSION
+setup.cfg
+setup.py
+graphql_mcp/__init__.py
+graphql_mcp/server.py
+graphql_mcp.egg-info/PKG-INFO
+graphql_mcp.egg-info/SOURCES.txt
+graphql_mcp.egg-info/dependency_links.txt
+graphql_mcp.egg-info/requires.txt
+graphql_mcp.egg-info/top_level.txt
+tests/__init__.py
+tests/test_graphql_mcp.py

graphql_mcp-1.0.0/graphql_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

graphql_mcp-1.0.0/graphql_mcp.egg-info/requires.txt

@@ -0,0 +1,12 @@
+graphql-core~=3.1
+fastmcp~=2.9
+graphql-api>=1.3.0
+
+[dev]
+graphql-api>=1.3.0
+pytest~=5.4
+pytest-cov~=2.10
+coverage~=5.2
+faker~=4.1
+fastmcp~=2.9
+pytest-asyncio~=0.18

graphql_mcp-1.0.0/graphql_mcp.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+graphql_mcp
+tests

graphql_mcp-1.0.0/setup.cfg

@@ -0,0 +1,15 @@
+[metadata]
+description_file = README.md
+
+[tool:pytest]
+filterwarnings = 
+	ignore:PYTEST_DONT_REWRITE:DeprecationWarning
+	ignore:ast.Str is deprecated and will be removed in Python 3.14; use ast.Constant instead:DeprecationWarning:docstring_parser.attrdoc
+
+[flake8]
+ignore = E501, W503, E402
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

graphql_mcp-1.0.0/setup.py

@@ -0,0 +1,51 @@
+import io
+
+from setuptools import setup, find_packages
+
+with io.open("README.md", "rt", encoding="utf8") as readme_file:
+    readme = readme_file.read()
+
+with io.open("VERSION") as version_file:
+    version = version_file.read().strip().lower()
+    if version.startswith("v"):
+        version = version[1:]
+
+setup(
+    name="graphql_mcp",
+    version=version,
+    license="MIT",
+    packages=find_packages(),
+    include_package_data=True,
+    author="Robert Parker",
+    author_email="rob@parob.com",
+    url="https://gitlab.com/parob/graphql-mcp",
+    download_url=f"https://gitlab.com/parob/graphql-mcp/-/archive/v{version}"
+    f"/graphql_mcp-v{version}.tar.gz",
+    keywords=["GraphQL", "GraphQL-API", "GraphQLAPI", "Server", "MCP", "Multi-Model-Protocol"],
+    description="A framework for building Python GraphQL MCP servers.",
+    long_description=readme,
+    long_description_content_type="text/markdown",
+    install_requires=[
+        "graphql-core~=3.1",
+        "fastmcp~=2.9",
+        "graphql-api>=1.3.0"
+    ],
+    extras_require={
+        "dev": [
+            "graphql-api>=1.3.0",
+            "pytest~=5.4",
+            "pytest-cov~=2.10",
+            "coverage~=5.2",
+            "faker~=4.1",
+            "fastmcp~=2.9",
+            "pytest-asyncio~=0.18",
+        ]
+    },
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+)

graphql_mcp-1.0.0/tests/__init__.py

@@ -0,0 +1,8 @@
+# flake8: noqa
+from __future__ import annotations
+
+from graphql_api.api import GraphQLAPI
+from graphql_api.decorators import field, type
+from graphql_api.error import GraphQLError
+from graphql_api.executor import GraphQLExecutor
+from graphql_api.reduce import GraphQLFilter, TagFilter

graphql_mcp-1.0.0/tests/test_graphql_mcp.py

@@ -0,0 +1,402 @@
+import json
+import pytest
+import enum
+
+from pydantic import BaseModel
+from graphql_api import GraphQLAPI
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from mcp.types import TextContent
+from typing import cast
+
+from graphql_mcp.server import from_graphql_schema
+
+
+@pytest.mark.asyncio
+async def test_from_graphql_schema():
+    api = GraphQLAPI()
+
+    @api.type(is_root_type=True)
+    class Root:
+        @api.field
+        def hello(self, name: str) -> str:
+            """Returns a greeting."""
+            return f"Hello, {name}"
+
+        @api.field(mutable=True)
+        def add(self, a: int, b: int) -> int:
+            """Adds two numbers."""
+            return a + b
+
+    schema, _ = api.build_schema()
+
+    mcp_server = await from_graphql_schema(schema)
+
+    async with Client(mcp_server) as client:
+        # Test query
+        result = await client.call_tool("hello", {"name": "World"})
+        assert cast(TextContent, result[0]).text == "Hello, World"
+
+        # Test mutation
+        result = await client.call_tool("add", {"a": 5, "b": 3})
+        assert cast(TextContent, result[0]).text == "8"
+
+        # Test tool listing
+        tools = await client.list_tools()
+        tool_names = {t.name for t in tools}
+        assert "hello" in tool_names
+        assert "add" in tool_names
+
+        hello_tool = next(t for t in tools if t.name == "hello")
+        assert hello_tool.description == "Returns a greeting."
+
+        add_tool = next(t for t in tools if t.name == "add")
+        assert add_tool.description == "Adds two numbers."
+
+
+@pytest.mark.asyncio
+async def test_from_graphql_schema_nested():
+    """
+    Tests the schema mapping with a nested object type.
+    """
+    api = GraphQLAPI()
+
+    @api.type
+    class Book:
+        @api.field
+        def title(self) -> str:
+            return "The Hitchhiker's Guide to the Galaxy"
+
+    @api.type
+    class Author:
+        @api.field
+        def name(self) -> str:
+            return "Douglas Adams"
+
+        @api.field
+        def book(self) -> Book:
+            return Book()
+
+    @api.type(is_root_type=True)
+    class Root:
+        @api.field
+        def author(self) -> Author:
+            return Author()
+
+    schema, _ = api.build_schema()
+
+    mcp_server = await from_graphql_schema(schema)
+
+    async with Client(mcp_server) as client:
+        result = await client.call_tool("author", {})
+        data = json.loads(cast(TextContent, result[0]).text)
+        assert data["name"] == "Douglas Adams"
+        assert data["book"]["title"] == "The Hitchhiker's Guide to the Galaxy"
+
+
+@pytest.mark.asyncio
+async def test_from_graphql_schema_advanced():
+    """
+    Tests more advanced schema features like enums, lists, and mutations on data.
+    """
+    api = GraphQLAPI()
+
+    class Status(enum.Enum):
+        PENDING = "PENDING"
+        COMPLETED = "COMPLETED"
+
+    # In-memory "database"
+    items_db = {
+        1: {"id": 1, "name": "Task 1", "completed": False, "status": Status.PENDING},
+        2: {"id": 2, "name": "Task 2", "completed": True, "status": Status.COMPLETED},
+    }
+
+    @api.type
+    class Item:
+        def __init__(self, **data):
+            self._data = data
+
+        @api.field
+        def id(self) -> int:
+            return self._data["id"]
+
+        @api.field
+        def name(self) -> str:
+            return self._data["name"]
+
+        @api.field
+        def completed(self) -> bool:
+            return self._data["completed"]
+
+        @api.field
+        def status(self) -> Status:
+            return self._data["status"]
+
+        @api.field(mutable=True)
+        def rename(self, new_name: str) -> 'Item':
+            """Updates the status of an item."""
+            self._data["name"] = new_name
+            return self
+
+    @api.type(is_root_type=True)
+    class Root:
+        @api.field
+        def items(self) -> list[Item]:
+            """Returns all items."""
+            return [Item(**item_data) for item_data in items_db.values()]
+
+        @api.field
+        def item(self, id: int) -> Item | None:
+            """Returns a single item by ID."""
+            if id in items_db:
+                return Item(**items_db[id])
+            return None
+
+        @api.field
+        def filter_items(
+            self, completed: bool, status: str | None = None
+        ) -> list[Item]:
+            """Filters items by completion status and optionally by enum status."""
+            filtered_data = [
+                i for i in items_db.values() if i["completed"] == completed
+            ]
+            if status:
+                filtered_data = [
+                    i for i in filtered_data if i["status"].value == status
+                ]
+            return [Item(**i) for i in filtered_data]
+
+        @api.field(mutable=True)
+        def update_item_status(self, id: int, status: str) -> Item:
+            """Updates the status of an item."""
+            if id not in items_db:
+                raise ValueError(f"Item with ID {id} not found.")
+            items_db[id]["status"] = Status(status)
+            return Item(**items_db[id])
+
+    schema, _ = api.build_schema()
+    mcp_server = await from_graphql_schema(schema)
+
+    async with Client(mcp_server) as client:
+        # 1. Test list return
+        result = await client.call_tool("items", {})
+        data = json.loads(cast(TextContent, result[0]).text)
+        assert len(data) == 2
+        assert data[0]["name"] == "Task 1"
+
+        # 2. Test query with arguments
+        result = await client.call_tool("item", {"id": 1})
+        data = json.loads(cast(TextContent, result[0]).text)
+        assert data["name"] == "Task 1"
+        assert data["status"] == "PENDING"
+
+        # 3. Test mutation
+        result = await client.call_tool("update_item_status", {"id": 1, "status": "COMPLETED"})
+        data = json.loads(cast(TextContent, result[0]).text)
+        assert data["status"] == "COMPLETED"
+
+        # 4. Test enum argument
+        result = await client.call_tool("filter_items", {"completed": True, "status": "COMPLETED"})
+        data = json.loads(cast(TextContent, result[0]).text)
+        if isinstance(data, dict):
+            data = [data]
+        assert len(data) == 1
+        assert data[0]["name"] == "Task 2"
+
+        # 5. Verify that mutations on nested objects are NOT exposed as top-level tools.
+        # The `graphql-api` library only creates top-level mutations from methods
+        # on the class marked `is_root_type=True`. The `rename` method on the
+        # `Item` type is therefore not mapped to a top-level mutation.
+        all_tools = await client.list_tools()
+        assert "rename" not in [tool.name for tool in all_tools]
+        assert "rename_item" not in [tool.name for tool in all_tools]
+
+
+@pytest.mark.asyncio
+async def test_from_graphql_schema_with_existing_server():
+    """
+    Tests that the schema mapping can be applied to an existing FastMCP server.
+    """
+    api = GraphQLAPI()
+
+    @api.type(is_root_type=True)
+    class Root:
+        @api.field
+        def new_tool(self) -> str:
+            return "new"
+
+    schema, _ = api.build_schema()
+
+    # 1. Create a server with a pre-existing tool
+    mcp_server = FastMCP()
+
+    @mcp_server.tool
+    def existing_tool() -> str:
+        """An existing tool."""
+        return "existing"
+
+    # 2. Populate the server from the schema
+    await from_graphql_schema(schema, server=mcp_server)
+
+    # 3. Verify both the old and new tools exist
+    async with Client(mcp_server) as client:
+        all_tools = await client.list_tools()
+        tool_names = [tool.name for tool in all_tools]
+        assert "existing_tool" in tool_names
+        assert "new_tool" in tool_names
+
+        # 4. Verify both tools are callable
+        result_existing = await client.call_tool("existing_tool", {})
+        assert cast(TextContent, result_existing[0]).text == "existing"
+
+        result_new = await client.call_tool("new_tool", {})
+        assert cast(TextContent, result_new[0]).text == "new"
+
+
+@pytest.mark.asyncio
+async def test_from_graphql_schema_core_only():
+    """
+    Tests that the schema mapping works with a schema built using only graphql-core.
+    """
+    from graphql import (
+        GraphQLSchema,
+        GraphQLObjectType,
+        GraphQLField,
+        GraphQLString,
+        GraphQLArgument,
+    )
+
+    def resolve_hello(root, info, name="world"):
+        return f"Hello, {name}"
+
+    query_type = GraphQLObjectType(
+        name="Query",
+        fields={
+            "hello": GraphQLField(
+                GraphQLString,
+                args={"name": GraphQLArgument(GraphQLString, default_value="world")},
+                resolve=resolve_hello,
+            )
+        },
+    )
+
+    schema = GraphQLSchema(query=query_type)
+
+    mcp_server = await from_graphql_schema(schema)
+
+    async with Client(mcp_server) as client:
+        # Test query
+        result = await client.call_tool("hello", {"name": "core"})
+        assert cast(TextContent, result[0]).text == "Hello, core"
+
+        tools = await client.list_tools()
+        assert len(tools) == 1
+        assert tools[0].name == "hello"
+
+
+@pytest.mark.asyncio
+async def test_error_handling():
+    """Tests that GraphQL errors are raised as exceptions."""
+    from graphql import (
+        GraphQLSchema,
+        GraphQLObjectType,
+        GraphQLField,
+        GraphQLString,
+    )
+    from fastmcp.exceptions import ToolError
+
+    def resolve_error(root, info):
+        raise ValueError("This is a test error")
+
+    query_type = GraphQLObjectType(
+        name="Query",
+        fields={
+            "error_field": GraphQLField(
+                GraphQLString,
+                resolve=resolve_error,
+            )
+        },
+    )
+    schema = GraphQLSchema(query=query_type)
+    mcp_server = await from_graphql_schema(schema)
+
+    async with Client(mcp_server) as client:
+        with pytest.raises(ToolError, match="This is a test error"):
+            await client.call_tool("error_field", {})
+
+
+@pytest.mark.asyncio
+async def test_from_graphql_schema_with_pydantic_input():
+    """
+    Tests that a mutation with a pydantic model as input is correctly handled.
+    """
+    api = GraphQLAPI()
+
+    class CreateItemInput(BaseModel):
+        name: str
+        price: float
+
+    @api.type
+    class Item:
+        @api.field
+        def name(self) -> str:
+            return "Test Item"
+
+        @api.field
+        def price(self) -> float:
+            return 12.34
+
+    @api.type(is_root_type=True)
+    class Root:
+        @api.field(mutable=True)
+        def create_item(self, input: dict) -> Item:
+            """Creates an item."""
+            # In a real scenario, you'd use the input to create the item.
+            # Here we just return a dummy item to verify the tool call.
+            if isinstance(input, str):
+                input = json.loads(input)
+            assert input["name"] == "My Pydantic Item"
+            assert input["price"] == 99.99
+            return Item()
+
+    schema, _ = api.build_schema()
+
+    mcp_server = await from_graphql_schema(schema)
+
+    async with Client(mcp_server) as client:
+        input_data = CreateItemInput(name="My Pydantic Item", price=99.99)
+        result = await client.call_tool("create_item", {"input": input_data})
+        data = json.loads(cast(TextContent, result[0]).text)
+        assert data["name"] == "Test Item"
+        assert data["price"] == 12.34
+
+
+@pytest.mark.asyncio
+async def test_from_graphql_schema_with_pydantic_output():
+    """
+    Tests that a query that returns a pydantic model is correctly handled.
+    """
+    api = GraphQLAPI()
+
+    class ItemOutput(BaseModel):
+        name: str
+        price: float
+        is_offer: bool = False
+
+    @api.type(is_root_type=True)
+    class Root:
+        @api.field
+        def get_item(self) -> ItemOutput:
+            """Gets an item."""
+            return ItemOutput(name="A Pydantic Item", price=42.0, is_offer=True)
+
+    schema, _ = api.build_schema()
+
+    mcp_server = await from_graphql_schema(schema)
+
+    async with Client(mcp_server) as client:
+        result = await client.call_tool("get_item", {})
+        data = json.loads(cast(TextContent, result[0]).text)
+        assert data["name"] == "A Pydantic Item"
+        assert data["price"] == 42.0
+        assert data["isOffer"] is True