### Setup Development Environment and Run Tests

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Installs development dependencies, runs tests using pytest, formats code with black and isort, and performs type checking with mypy. This snippet is crucial for setting up a local development environment and ensuring code quality.

```bash
# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
isort .

# Type checking
mypy src/
```

--------------------------------

### Development Setup for Text-to-GraphQL MCP Server

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Installs development dependencies for the text-to-graphql-mcp project using UV. This command is intended for developers contributing to the project.

```bash
uv sync --dev
```

--------------------------------

### Install Dependencies with UV

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Installs project dependencies using the UV package manager. UV automatically creates and manages a virtual environment for the project, ensuring a clean and reliable setup.

```bash
uv sync
```

--------------------------------

### Test Text-to-GraphQL MCP Server Installation

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Tests the installation of the text-to-graphql-mcp server by running its help command using UV. This verifies that the server is accessible and configured correctly.

```bash
uv run text-to-graphql-mcp --help
```

--------------------------------

### Install Text-to-GraphQL MCP Server from PyPI

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Installs the text-to-graphql-mcp server from the Python Package Index (PyPI) using pip. This is an alternative installation method available when the package is published.

```bash
pip install text-to-graphql-mcp
```

--------------------------------

### Install UV Package Manager (Windows)

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Installs the UV package manager on Windows systems using PowerShell. UV is a fast Python package installer and resolver, recommended for managing project dependencies.

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Environment Configuration (.env example)

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Example of an environment file (.env) for configuring the server, particularly for production deployments. It specifies required variables for OpenAI API key, GraphQL endpoint URL, and authentication credentials.

```bash
# .env file example for production deployment

# Required: OpenAI API key for LLM operations
OPENAI_API_KEY=sk-proj-your-openai-api-key-here

# Required: GraphQL endpoint URL
GRAPHQL_ENDPOINT=https://api.example.com/graphql

# Required: Authentication credentials
GRAPHQL_API_KEY=your-graphql-api-key-here
GRAPHQL_AUTH_TYPE=bearer  # Options: bearer, apikey, direct
```

--------------------------------

### Retrieve Query Examples (Python)

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Provides example natural language queries to illustrate the system's capabilities and common query patterns. This function is useful for understanding how to interact with the system and does not require any parameters.

```python
# Example call (no parameters required)
# Returns:
{
  "examples": [
    {
      "query": "Get all users with their names and emails"
    },
    {
      "query": "Find posts by author ID 123"
    },
    {
      "query": "List all products with prices above $50"
    },
    {
      "query": "Get user profile including posts and comments"
    },
    {
      "query": "Search for posts containing 'GraphQL'"
    }
  ]
}
```

--------------------------------

### GitHub GraphQL API Configuration Example

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

An example of environment variables for configuring the Text-to-GraphQL MCP to connect to the GitHub GraphQL API. It specifies the endpoint URL, API key, and authentication type.

```env
GRAPHQL_ENDPOINT=https://api.github.com/graphql
GRAPHQL_API_KEY=ghp_your_github_personal_access_token
GRAPHQL_AUTH_TYPE=bearer
```

--------------------------------

### GraphQL Query Generation Example

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This example demonstrates the 'generate_graphql_query' tool, which converts natural language input into a valid GraphQL query. It shows a sample input and its corresponding output query.

```text
Input: "Get all users with their names and emails"
Output: query { users { id name email } }
```

--------------------------------

### Install UV Package Manager (macOS/Linux)

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Installs the UV package manager on macOS and Linux systems using a curl command. UV is a fast Python package installer and resolver, recommended for managing project dependencies.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Hasura GraphQL API Configuration Example

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

An example of environment variables for configuring the Text-to-GraphQL MCP to connect to a Hasura GraphQL API. This example uses custom headers for authentication, overriding the default auth type.

```env
GRAPHQL_ENDPOINT=https://your-app.hasura.app/v1/graphql
GRAPHQL_HEADERS={"x-hasura-admin-secret": "your_admin_secret"}
```

--------------------------------

### Install Arize Phoenix for LLM Observability

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Installs the Arize Phoenix library, an open-source observability platform for LLM applications and agents. It is used for real-time monitoring, trace visualization, and evaluation frameworks. This command is essential for developers looking to monitor and debug their AI agents.

```bash
pip install arize-phoenix
phoenix serve
```

--------------------------------

### Find UV Installation Path

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This Bash script demonstrates how to find the installation path of the 'uv' (likely a Python virtual environment manager) on different operating systems. This path is crucial for correctly setting up environment variables in the MCP configuration.

```bash
# Find your UV installation
which uv

# Common paths by OS:
# macOS: /Users/yourusername/.local/bin/uv
# Linux: /home/yourusername/.local/bin/uv  
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin\uv.exe

# For MCP config, use the directory path:
# macOS: /Users/yourusername/.local/bin
# Linux: /home/yourusername/.local/bin
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin
```

--------------------------------

### Shopify GraphQL API Configuration Example

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

An example of environment variables for configuring the Text-to-GraphQL MCP to connect to a Shopify GraphQL API. It includes the endpoint URL, access token, and authentication type.

```env
GRAPHQL_ENDPOINT=https://your-shop.myshopify.com/admin/api/2023-10/graphql.json
GRAPHQL_API_KEY=your_shopify_access_token
GRAPHQL_AUTH_TYPE=bearer
```

--------------------------------

### Build Docker Image for text-to-graphql-mcp

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

These Bash commands guide the process of building a Docker image for the text-to-graphql-mcp project. It includes cloning the repository and executing the Docker build command.

```bash
# Clone the repository
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp

# Build the Docker image
docker build -t text-to-graphql-mcp .
```

--------------------------------

### Clone Text-to-GraphQL MCP Server Repository

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Clones the text-to-graphql-mcp repository from GitHub using git. This command downloads the project files to your local machine for setup and development.

```bash
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp
```

--------------------------------

### Arize GraphQL API Configuration Example

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

An example of environment variables for configuring the Text-to-GraphQL MCP to connect to the Arize GraphQL API. It specifies the endpoint URL and API key, noting that the authentication type is auto-detected.

```env
GRAPHQL_ENDPOINT=https://app.arize.com/graphql
GRAPHQL_API_KEY=your_arize_developer_api_key
# Auth type auto-detected for Arize
```

--------------------------------

### Natural Language to GraphQL Conversion Example

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This example illustrates a practical use case of the text-to-graphql-mcp tool, converting a natural language request for blog posts into a complex GraphQL query. The generated query includes filtering by date and fetching related author and comment data.

```graphql
query {
  posts(where: { createdAt: { gte: "2024-06-05T00:00:00Z" } }) {
    id
    title
    content
    createdAt
    author {
      id
      name
      email
    }
    comments {
      id
    }
    _count {
      comments
    }
  }
}
```

--------------------------------

### Configure MCP with .env File

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This example shows how to define environment variables in a .env file, which can then be used to simplify the MCP configuration. It includes essential keys like API keys and GraphQL endpoint, as well as optional settings for model and authentication type.

```env
# Required
OPENAI_API_KEY=your_openai_api_key_here
GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql
GRAPHQL_API_KEY=your_api_key_here

# Optional - Authentication method (bearer|apikey|direct)
GRAPHQL_AUTH_TYPE=bearer

# Optional - Model settings
MODEL_NAME=gpt-4o
MODEL_TEMPERATURE=0
```

--------------------------------

### Docker Commands for Managing Text-to-GraphQL MCP Service

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

A set of bash commands to manage the Text-to-GraphQL MCP service when deployed via Docker Compose. These commands include starting the service in detached mode, viewing logs, and stopping the service.

```bash
# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down
```

--------------------------------

### Cursor Configuration for Text-to-GraphQL MCP

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This JSON configuration is used by Cursor to connect to the Text-to-GraphQL MCP service running inside a Docker container. It specifies the command to execute within the container to start the MCP server.

```json
{
  "text-to-graphql": {
    "command": "docker",
    "args": [
      "exec",
      "-i",
      "text-to-graphql-mcp",
      "uv",
      "run",
      "python",
      "-m",
      "src.text_to_graphql_mcp.mcp_server"
    ]
  }
}
```

--------------------------------

### Validate GraphQL Query against Schema

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Validates GraphQL queries against a loaded schema to ensure correctness before execution. It provides detailed error messages and suggestions for improvement if the query is invalid. Both valid and invalid query examples are demonstrated.

```python
# Example validation of a query
# Input parameters:
{
  "graphql_query": "query { users { id name email invalidField } }",
  "natural_language_query": "Get all users",
  "history_id": "1"
}

# Returns:
{
  "history_id": "1",
  "validation_result": {
    "is_valid": false,
    "errors": [
      {
        "message": "Field 'invalidField' does not exist on type 'User'",
        "location": "users.invalidField"
      }
    ],
    "warnings": [],
    "suggestions": [
      "Available fields on User: id, name, email, createdAt, updatedAt"
    ]
  }
}

# Valid query example:
{
  "graphql_query": "query { users { id name email } }",
  "natural_language_query": "Get all users"
}

# Returns:
{
  "history_id": "2",
  "validation_result": {
    "is_valid": true,
    "errors": [],
    "warnings": []
  }
}
```

--------------------------------

### Docker Deployment for text-to-graphql-mcp

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Instructions for building and running the text-to-graphql-mcp service using Docker. This includes commands for building the image, running a container with environment variables, and setting up Docker Compose for a more robust deployment, including health checks.

```bash
# Build the Docker image
docker build -t text-to-graphql-mcp .

# Run with environment variables
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  -e OPENAI_API_KEY="sk-proj-your-key-here" \
  -e GRAPHQL_ENDPOINT="https://api.example.com/graphql" \
  -e GRAPHQL_API_KEY="your-api-key-here" \
  -e GRAPHQL_AUTH_TYPE="bearer" \
  -e MODEL_NAME="gpt-4o" \
  text-to-graphql-mcp

# Or use Docker Compose with environment file
cat > .env << EOF
OPENAI_API_KEY=sk-proj-your-key-here
GRAPHQL_ENDPOINT=https://api.example.com/graphql
GRAPHQL_API_KEY=your-api-key-here
GRAPHQL_AUTH_TYPE=bearer
MODEL_NAME=gpt-4o
MODEL_TEMPERATURE=0
EOF

# docker-compose.yml
cat > docker-compose.yml << EOF
version: '3.8'
services:
  text-to-graphql-mcp:
    build: .
    container_name: text-to-graphql-mcp
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GRAPHQL_ENDPOINT=${GRAPHQL_ENDPOINT}
      - GRAPHQL_API_KEY=${GRAPHQL_API_KEY}
      - GRAPHQL_AUTH_TYPE=${GRAPHQL_AUTH_TYPE:-bearer}
      - MODEL_NAME=${MODEL_NAME:-gpt-4o}
      - MODEL_TEMPERATURE=${MODEL_TEMPERATURE:-0}
      - API_HOST=0.0.0.0
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
EOF

docker-compose up -d

# Configure MCP clients to use Docker container
# Add to .cursor/mcp.json or Claude Desktop config:
{
  "text-to-graphql": {
    "command": "docker",
    "args": [
      "exec",
      "-i",
      "text-to-graphql-mcp",
      "uv",
      "run",
      "python",
      "-m",
      "src.text_to_graphql_mcp.mcp_server"
    ]
  }
}
```

--------------------------------

### Run text-to-graphql-mcp Server

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

These Bash commands show two ways to run the text-to-graphql-mcp server, either directly as an executable or as a Python module. These are useful for testing the server locally.

```bash
# Run the server directly for testing
text-to-graphql-mcp

# Or run as a module
python -m text_to_graphql_mcp.mcp_server
```

--------------------------------

### MCP Client Configuration using JSON

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Configuration for MCP clients like Cursor and Claude Desktop. This JSON structure defines how to run the text-to-graphql-mcp service, including command execution, arguments, and environment variables for API keys and endpoints.

```json
// Cursor configuration: .cursor/mcp.json
{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/Users/yourusername/projects/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/Users/yourusername/.local/bin:/usr/bin:/bin",
      "OPENAI_API_KEY": "sk-proj-your-key-here",
      "GRAPHQL_ENDPOINT": "https://api.example.com/graphql",
      "GRAPHQL_API_KEY": "your-api-key-here",
      "GRAPHQL_AUTH_TYPE": "bearer"
    }
  }
}
```

```json
// Claude Desktop configuration:
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "text-to-graphql": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/text-to-graphql-mcp",
        "run",
        "text-to-graphql-mcp"
      ],
      "env": {
        "PATH": "/path/to/uv/bin:/usr/bin:/bin",
        "OPENAI_API_KEY": "sk-proj-your-key-here",
        "GRAPHQL_ENDPOINT": "https://api.example.com/graphql",
        "GRAPHQL_API_KEY": "your-api-key-here",
        "GRAPHQL_AUTH_TYPE": "bearer"
      }
    }
  }
}
```

--------------------------------

### Docker Run Command for Text-to-GraphQL MCP with Environment Variables

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This command demonstrates how to run the Text-to-GraphQL MCP service as a Docker container, mapping ports and loading environment variables from a .env file. It also includes a command to verify that the container is running.

```bash
# Example: Make sure the container is running with your environment variables
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  --env-file .env \
  text-to-graphql-mcp

# Verify the container is running
docker ps | grep text-to-graphql-mcp
```

--------------------------------

### Simplified MCP Configuration with .env

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This JSON configuration is a simplified version for Claude Desktop's MCP when using a .env file for environment variables. It still requires the PATH to be set correctly.

```json
{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin"
    }
  }
}
```

--------------------------------

### Configure Text-to-GraphQL MCP Server with Cursor

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

Configuration snippet for the Text-to-GraphQL MCP Server within Cursor's MCP client settings. It specifies the command to run the server, environment variables including API keys and GraphQL endpoint details.

```json
{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin",
      "OPENAI_API_KEY": "your_openai_api_key_here",
      "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
      "GRAPHQL_API_KEY": "your_api_key_here",
      "GRAPHQL_AUTH_TYPE": "bearer"
    }
  }
}
```

--------------------------------

### Environment Variables for Text-to-GraphQL MCP

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

A table listing the environment variables required for configuring the Text-to-GraphQL MCP service. It includes descriptions, default values, and specifies which variables are mandatory.

```env
OPENAI_API_KEY=Required
GRAPHQL_ENDPOINT=Required
GRAPHQL_API_KEY=Required
GRAPHQL_AUTH_TYPE=bearer
GRAPHQL_HEADERS={}
MODEL_NAME=gpt-4o
MODEL_TEMPERATURE=0
API_HOST=127.0.0.1
API_PORT=8000
RECURSION_LIMIT=10
```

--------------------------------

### Run Docker Container with Environment File

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This Docker command runs the text-to-graphql-mcp container using an environment file. This method is cleaner for managing multiple environment variables, especially sensitive ones like API keys.

```bash
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  --env-file .env \
  text-to-graphql-mcp
```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This JSON configuration is used for Claude Desktop's MCP (Meta-Contextual Processing) to connect to the text-to-graphql-mcp service. It specifies the command to run, arguments, and environment variables including API keys and GraphQL endpoints.

```json
{
  "mcpServers": {
    "text-to-graphql": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/text-to-graphql-mcp",
        "run",
        "text-to-graphql-mcp"
      ],
      "env": {
        "PATH": "/path/to/uv/bin:/usr/bin:/bin",
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
        "GRAPHQL_API_KEY": "your_api_key_here",
        "GRAPHQL_AUTH_TYPE": "bearer"
      }
    }
  }
}
```

--------------------------------

### Claude Desktop Configuration for Text-to-GraphQL MCP

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This JSON configuration allows Claude Desktop to connect to the Text-to-GraphQL MCP service running in a Docker container. It defines the necessary command to execute within the container to interact with the MCP server.

```json
{
  "mcpServers": {
    "text-to-graphql": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "text-to-graphql-mcp",
        "uv",
        "run",
        "python",
        "-m",
        "src.text_to_graphql_mcp.mcp_server"
      ]
    }
  }
}
```

--------------------------------

### Construct GraphQL Query and Mutation Contexts - Python

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Demonstrates how to construct context objects for GraphQL queries and mutations using helper functions. This requires a loaded GraphQL schema and specifies the type of operation (query or mutation) and the target field or operation name. The output provides the relevant schema definitions for the specified context.

```python
from text_to_graphql_mcp.tools.graphql_helpers import (
    construct_query_context,
    construct_mutation_context,
    execute_graphql_query
)

# Construct context for a query field
schema = load_graphql_schema(endpoint_url=settings.GRAPHQL_ENDPOINT)
query_context = construct_query_context(schema, "users")
print(query_context)
# Output: Relevant GraphQL type definitions for 'users' query
# type Query {
#   users(first: Int, after: String): UserConnection
# }
# 
# type UserConnection {
#   edges: [UserEdge]
#   pageInfo: PageInfo
# }
# ...

# Construct context for a mutation
mutation_context = construct_mutation_context(schema, "createUser")
print(mutation_context)
# Output: Mutation definition with input/output types
# type Mutation {
#   createUser(input: CreateUserInput!): CreateUserPayload
# }
# 
# input CreateUserInput {
#   name: String!
#   email: String!
# }
# ...
```

--------------------------------

### GraphQL Agent Operations (Python)

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Demonstrates various operations performed by the GraphQLAgent, including generating queries from natural language, validating GraphQL queries, executing queries with variables, and visualizing data. These are asynchronous functions requiring appropriate inputs and session IDs.

```python
from text_to_graphql_mcp.agent import GraphQLAgent
import asyncio

# Initialize the agent
agent = GraphQLAgent()

# Generate a query from natural language
async def generate_query_example():
    result = await agent.generate_query(
        natural_language_query="Get all users who registered in the last month",
        session_id="unique-session-123"
    )

    print(f"Generated Query:\n{result['graphql_query']}")
    print(f"Is Valid: {result['validation_result']['is_valid']}")
    # Output:
    # Generated Query:
    # query {
    #   users(where: { createdAt: { gte: "2025-09-19T00:00:00Z" } }) {
    #     id
    #     name
    #     email
    #     createdAt
    #   }
    # }
    # Is Valid: True

# Validate a custom query
async def validate_query_example():
    result = await agent.validate_query(
        graphql_query="query { users { id name email age } }",
        natural_language_query="Get user data",
        session_id="session-456"
    )

    print(f"Valid: {result['is_valid']}")
    print(f"Errors: {result.get('errors', [])}")

# Execute a query with variables
async def execute_query_example():
    result = await agent.execute_query(
        graphql_query="""
            query GetUserPosts($userId: ID!, $limit: Int!) {
                user(id: $userId) {
                    name
                    posts(first: $limit) {
                        title
                        publishedAt
                    }
                }
            }
        """,
        variables={"userId": "user-789", "limit": 10}
    )

    print(f"Success: {result['success']}")
    print(f"Data: {result['data']}")
    print(f"Execution Time: {result['execution_time']}s")

# Visualize query results
async def visualize_data_example():
    data = {
        "users": [
            {"name": "Alice", "postCount": 15, "role": "admin"},
            {"name": "Bob", "postCount": 8, "role": "user"},
            {"name": "Charlie", "postCount": 23, "role": "moderator"}
        ]
    }

    result = await agent.visualize_data(
        data=data,
        natural_language_query="Show user post statistics"
    )

    print(f"Visualizations: {len(result['visualizations'])}")
    for viz in result['visualizations']:
        print(f"  - {viz['type']}: {viz['title']}")
    # Output:
    # Visualizations: 2
    #   - bar_chart: User Post Count by Name
    #   - table: User Statistics

asyncio.run(generate_query_example())
```

--------------------------------

### Docker Compose Configuration for Text-to-GraphQL MCP

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This configuration file defines the services, ports, environment variables, and health checks for running the Text-to-GraphQL MCP service using Docker Compose. It allows for easy deployment and management of the service in a containerized environment.

```yaml
version: '3.8'

services:
  text-to-graphql-mcp:
    build: .
    container_name: text-to-graphql-mcp
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GRAPHQL_ENDPOINT=${GRAPHQL_ENDPOINT}
      - GRAPHQL_API_KEY=${GRAPHQL_API_KEY}
      - GRAPHQL_AUTH_TYPE=${GRAPHQL_AUTH_TYPE:-bearer}
      - MODEL_NAME=${MODEL_NAME:-gpt-4o}
      - MODEL_TEMPERATURE=${MODEL_TEMPERATURE:-0}
      - API_HOST=0.0.0.0  # Important: bind to all interfaces in container
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

--------------------------------

### Execute GraphQL Query and Recommend Visualizations

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Executes validated GraphQL queries against the configured endpoint, supporting variables for dynamic queries. It returns the execution results, including response data and any errors, along with visualization recommendations based on the data structure.

```python
# Example execution with variables
# Input parameters:
{
  "graphql_query": "query GetUser($userId: ID!) { user(id: $userId) { id name email posts { title } } }",
  "variables": {
    "userId": "123"
  },
  "natural_language_query": "Get user 123 with their posts",
  "history_id": "1"
}

# Returns:
{
  "history_id": "1",
  "execution_result": {
    "status": "SUCCESS",
    "response_data": {
      "user": {
        "id": "123",
        "name": "John Doe",
        "email": "john@example.com",
        "posts": [
          {"title": "First Post"},
          {"title": "Second Post"}
        ]
      }
    },
    "error": null,
    "execution_time": 0.234
  },
  "visualization_result": {
    "visualizations": [
      {
        "type": "table",
        "title": "User Posts",
        "config": {
          "columns": ["title"],
          "data_path": "user.posts"
        }
      }
    ],
    "recommendations": [
      "Consider using a bar chart to visualize post count over time"
    ]
  }
}

# Error handling example:
{
  "graphql_query": "query { nonExistentField }",
  "natural_language_query": "Get invalid data"
}

# Returns:
{
  "history_id": "2",
  "execution_result": {
    "status": "ERROR",
    "response_data": {},
    "error": "Cannot query field 'nonExistentField' on type 'Query'",
    "execution_time": 0.045
  },
  "visualization_result": null
}
```

--------------------------------

### Run Docker Container with Environment Variables

Source: https://github.com/arize-ai/text-to-graphql-mcp/blob/main/README.md

This Docker command runs the text-to-graphql-mcp container in detached mode. It maps port 8000, and crucially, sets all necessary environment variables directly on the command line for the container to use.

```bash
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  -e OPENAI_API_KEY="your_openai_api_key_here" \
  -e GRAPHQL_ENDPOINT="https://your-graphql-api.com/graphql" \
  -e GRAPHQL_API_KEY="your_api_key_here" \
  -e GRAPHQL_AUTH_TYPE="bearer" \
  -e MODEL_NAME="gpt-4o" \
  text-to-graphql-mcp
```

--------------------------------

### Execute GraphQL Query with Error Handling - Python

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Shows how to execute a GraphQL query against a specified endpoint, including parameters for the query, headers, variables, and operation name. It also demonstrates robust error handling by checking the 'success' field in the result and printing either the data or error messages.

```python
from text_to_graphql_mcp.tools.graphql_helpers import execute_graphql_query

# Execute GraphQL query with full error handling
result = execute_graphql_query(
    endpoint_url="https://api.example.com/graphql",
    query="""
        query GetUsers($limit: Int!) {
            users(first: $limit) {
                id
                name
                email
            }
        }
    """,
    headers={"Authorization": "Bearer token"},
    variables={"limit": 10},
    operation_name="GetUsers"
)

if result["success"]:
    print(f"Data: {result['data']}")
    # Output: Data: {'users': [{'id': '1', 'name': 'Alice', ...}]}
else:
    print(f"Error: {result['message']}")
    print(f"Exception Type: {result['exception']}")
```

--------------------------------

### Python Schema Management Helpers

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Python functions for managing GraphQL schemas within the text-to-graphql-mcp project. These functions allow loading schemas automatically, forcing introspection from an endpoint, or loading from a local cached file.

```python
from text_to_graphql_mcp.tools.schema_management import (
    load_graphql_schema,
    load_schema_via_introspection,
    load_schema_from_file
)
from text_to_graphql_mcp.config import settings

# Load schema with automatic fallback (introspection -> file -> default)
schema = load_graphql_schema(
    file_path="./cached_schema.graphql",
    endpoint_url="https://api.example.com/graphql",
    headers={"Authorization": "Bearer your-token"}
)
# Returns GraphQLSchema object or schema string

# Force introspection from endpoint
introspection_result = load_schema_via_introspection(
    endpoint_url="https://api.example.com/graphql",
    headers=settings.get_graphql_headers()
)
# Returns introspection JSON data

# Load from cached file
cached_schema = load_schema_from_file("./src/schema/api_example_com_schema.graphql")
# Returns parsed schema dict or None

```

--------------------------------

### Generate GraphQL Query using LangGraph

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Converts natural language descriptions into valid GraphQL queries using a LangGraph agent workflow. This process includes intent recognition, schema introspection, query construction, and validation. It returns the generated query along with its validation status.

```python
# Example using the MCP tool in Claude Desktop or Cursor
# User message: "Get all users with their names and emails"

# The tool processes this through the agent workflow and returns:
{
  "history_id": "1",
  "natural_language_query": "Get all users with their names and emails",
  "graphql_query": "query {
  users {
    id
    name
    email
  }
}",
  "validation_result": {
    "is_valid": true,
    "errors": [],
    "warnings": []
  }
}

# More complex example with filters:
# User message: "Find all blog posts from the last week with their authors and comment counts"

# Returns:
{
  "history_id": "2",
  "natural_language_query": "Find all blog posts from the last week with their authors and comment counts",
  "graphql_query": "query {
  posts(where: { createdAt: { gte: \"2025-10-12T00:00:00Z\" } }) {
    id
    title
    content
    createdAt
    author {
      id
      name
      email
    }
    _count {
      comments
    }
  }
}",
  "validation_result": {
    "is_valid": true,
    "errors": [],
    "warnings": []
  }
}
```

--------------------------------

### Retrieve Query History (Python)

Source: https://context7.com/arize-ai/text-to-graphql-mcp/llms.txt

Retrieves the complete history of queries processed in the current session. This includes natural language inputs, generated GraphQL, validation results, and execution results. No parameters are required for this function.

```python
# Example call (no parameters required)
# Returns:
{
  "history": [
    {
      "id": "1",
      "natural_language_query": "Get all users with their names and emails",
      "graphql_query": "query {\n  users {\n    id\n    name\n    email\n  }\n}",
      "validation_result": {
        "is_valid": true,
        "errors": [],
        "warnings": []
      },
      "execution_result": {
        "status": "SUCCESS",
        "response_data": {
          "users": [
            {"id": "1", "name": "Alice", "email": "alice@example.com"},
            {"id": "2", "name": "Bob", "email": "bob@example.com"}
          ]
        },
        "error": null,
        "execution_time": 0.156
      }
    },
    {
      "id": "2",
      "natural_language_query": "Find posts by author ID 123",
      "graphql_query": "query {\n  posts(where: { authorId: { equals: \"123\" } }) {\n    id\n    title\n    content\n  }\n}",
      "validation_result": {
        "is_valid": true,
        "errors": [],
        "warnings": []
      }
    }
  ]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.