Text-To-GraphQL

Converts natural language descriptions into valid GraphQL queries using a LangGraph-based agent that orchestrates multi-step workflows including intent recognition, schema analysis, query construction, and validation. The agent maintains state across steps and uses OpenAI's GPT-4o model to understand user intent and map it to GraphQL operations, handling complex nested queries and field selection automatically.

Fetches and parses GraphQL schema via introspection queries, extracting type definitions, fields, arguments, and relationships. The system caches schema metadata in memory during the agent session and uses it to validate query construction, providing the agent with a ground-truth representation of available operations without requiring manual schema definition.

Implements a structured exception hierarchy for different error types (schema errors, query construction errors, validation errors, execution errors), enabling fine-grained error handling and recovery. Each exception type carries context information (error message, affected query, suggestions) that helps the agent or user understand what went wrong and how to fix it.

Provides tools for handling ambiguous queries where multiple valid interpretations exist, presenting options to the user or agent and enabling selection of the intended interpretation. When a natural language query could map to multiple GraphQL operations or field selections, the system generates options and waits for disambiguation before proceeding.

Formats GraphQL query results for presentation to users, supporting multiple output formats (JSON, table, tree view) and handling large result sets gracefully. The system can truncate large results, highlight important fields, and provide summary statistics, making results more readable and actionable in AI assistant interfaces.

Analyzes natural language input to identify user intent (fetch, filter, aggregate, mutate) and maps it to GraphQL operations. Uses LLM-based reasoning to decompose complex requests into query components (root type, fields, filters, sorting, pagination) and generates a query plan before constructing the actual GraphQL syntax, enabling the agent to handle ambiguous or multi-step requests.

Builds valid GraphQL query syntax from intent and schema metadata, automatically selecting appropriate fields, constructing nested selections, and handling arguments. The system uses schema-aware field selection to include only requested fields and their required sub-fields, generating syntactically valid GraphQL that matches the schema structure without manual field enumeration.

Validates constructed GraphQL queries against the schema using graphql-core validation rules before execution, catching syntax errors, type mismatches, and invalid field selections. If validation fails, the agent analyzes the error and attempts recovery by reconstructing the query with corrections, providing detailed error messages to guide the user or the agent toward valid queries.

Executes validated GraphQL queries against the target endpoint using HTTPX HTTP client, handling authentication headers, timeouts, and response parsing. The system returns structured JSON results and handles GraphQL-specific error responses (including partial results with errors), providing clear error messages when execution fails and supporting both query and mutation operations.

Implements a FastMCP-based Model Context Protocol server that exposes text-to-graphql capabilities as MCP tools, enabling seamless integration with MCP clients like Claude Desktop and Cursor. The server registers tools for schema management, query construction, validation, and execution, handling MCP protocol serialization and client communication automatically.

Orchestrates the multi-step text-to-graphql workflow using LangGraph state machine, maintaining agent state across steps (intent, schema, query plan, constructed query, validation result, execution result). The agent transitions between states based on step outcomes, enabling error recovery, iterative refinement, and clear visibility into the query generation process.

Provides structured logging using Loguru with MCP mode detection, logging all agent steps, tool invocations, schema operations, and query execution with timestamps and context. The system detects whether it's running in MCP mode and adjusts logging output accordingly, enabling debugging and observability without interfering with MCP protocol communication.

Manages system configuration using Pydantic settings, supporting environment variables, configuration files, and runtime overrides. The system validates configuration at startup and provides sensible defaults for GraphQL endpoint, API keys, logging levels, and agent parameters, enabling flexible deployment across different environments.