gql-interface-adapter

GraphQL Schema → Intelligent Agent Interaction

gql-interface-adapter functions as an intermediary relay, transforming GraphQL operations into standardized Model Context Protocol (MCP) function definitions consumable by sophisticated language models such as Claude, Cursor, and ChatGPT.

Define your necessary data retrieval or modification procedures using standard GraphQL query or mutation syntax against your existing GraphQL service, and the adapter automatically provisions the necessary MCP serving infrastructure.

🔌 Backed directly by your existing GraphQL API endpoint ⚙️ Configuration driven by project-root .graphqlrc.yml alongside plain .graphql definition files

---

Key Capabilities

• 🧰 Tool definitions established through native GraphQL operation documents.
• 🗂 Automatic cataloging of executable operations referenced in .graphqlrc.yml.
• 🧾 Generated tool specifications adhere strictly to OpenAI function calling / MCP requirements.

---

🛠️ Installation Procedure

bash go install github.com/fotoetienne/gqai@latest

🚀 Initial Setup Guide

1. Establish a .graphqlrc.yml configuration file:

yaml schema: https://graphql.org/graphql/ documents: .

This file directs the adapter to locate the authoritative GraphQL schema definition and the files containing the operations intended for exposure.

Important Note: The schema directive mandates a live, accessible GraphQL endpoint URI, not merely a static schema file path.

1. Incorporate a specific GraphQL operation file

fetch_celestial_bodies.graphql: graphql

Retrieve all known cinematic space sagas

query retrieve_all_sagas { allFilms { films { title episodeID } } }

1. Integrate the adapter into your agent configuration (mcp.json):

"gql-interface-adapter": { "command": "gqai", "args": [ "run", "--config" ".graphqlrc.yml" ] }

Completion! Your AI agent is now equipped to invoke the retrieve_all_sagas tool.

Operation & Management

Configuration Details

GraphQL Service Definition

The GraphQL Configuration Specification utilizes YAML to define the target endpoint URI and the collection of operations designated for agent tool exposure. The expected filename is .graphqlrc.yml, situated in the project's root directory.

yaml schema: https://graphql.org/graphql/ documents: data_operations

The schema key points to the server URL, while documents specifies the directory containing operation definitions.

In this setup, any operation residing within the data_operations subdirectory, documented in .graphql files, will be automatically discovered and exposed.

Request Headers Customization

Custom HTTP headers can be injected into every request dispatched to the GraphQL backend. This feature is vital for incorporating authentication tokens or custom metadata.

yaml schema: - https://graphql.org/graphql/: headers: Authorization: Basic ENCODED_CREDENTIALS X-Client-ID: AdapterService documents: .

Utilizing Environment Variables within Headers

Header values can dynamically incorporate environment variables using the ${VARNAME} substitution syntax.

yaml schema: - https://graphql.org/graphql/: headers: Authorization: Bearer ${API_SECRET_KEY} documents: .

You can also specify a fallback value with the ${VARNAME:-default_value} syntax:

yaml schema: - https://graphql.org/graphql/: headers: Authorization: Bearer ${API_SECRET_KEY:-fallback-token-001} documents: .

Upon loading the configuration, the adapter substitutes ${API_SECRET_KEY} with the corresponding environment variable's content, or defaults to fallback-token-001 if the variable is undefined. This promotes keeping sensitive credentials external to configuration files.

If an environment variable is absent and no default is supplied, the literal placeholder string will persist.

Environment Variable Substitution Across Configuration

Environment variables are valid for substitution in any top-level .graphqlrc.yml directive: schema URIs, document paths, inclusion/exclusion patterns, and header values. Employ ${VARNAME} or ${VARNAME:-default}:

yaml schema: - ${GRAPHQL_ENDPOINT_URL:-https://default.api/graphql}: headers: Authorization: Bearer ${AUTH_TOKEN} documents: - ${OPERATION_DIR:-service_queries//.graphql} include: ${EXTRA_OPS_FILE:-system_defaults.graphql} exclude: ${IGNORED_OPS:-temp/.graphql}

The adapter resolves these placeholders using environmental data, allowing for environment-specific overrides of endpoints and paths without modifying the core configuration file.

MCP Integration Configuration

Compatibility with Desktop Environments

For operation within environments like Claude Desktop, ensure the following structure is present in your mcp.json manifest:

{ "gql-interface-adapter": { "command": "gqai", "args": [ "run", "--config", ".graphqlrc.yml" ] } }

🧪 CLI Diagnostic Invocation

Testing a Tool Invocation via Command Line:

bash gqai tools/invoke fetch_celestial_bodies

This command executes the specified tool synchronously and displays the JSON response payload.

shell { "data": { "allFilms": { "films": [ { "id": 4, "title": "A New Hope" }, { "id": 5, "title": "The Empire Strikes Back" }, { "id": 6, "title": "Return of the Jedi" }, ... ] } } }

Invoking a Tool Requiring Input Parameters:

First, define a GraphQL operation that accepts input variables:

obtain_saga_details.graphql: graphql query get_saga_by_episode($episodeNum: Int!) { saga(episode: $episodeNum) { title chronology primary_protagonist release_year } }

Execute the tool, passing the required arguments as a JSON string:

bash gqai tools/invoke obtain_saga_details '{"episodeNum": 4}'

This triggers the execution of the obtain_saga_details tool with the specified numeric ID.

shell { "data": { "saga": { "title": "A New Hope", "chronology": "IV", "primary_protagonist": "Luke Skywalker", "release_year": 1977 } } }

Development Cycle

Prerequisites

• Go Runtime Environment version 1.20 or newer

Building Artifacts

bash go build -o gqai ./main.go

Running Unit Tests

bash go test ./...

Code Formatting Enforcement

bash go fmt ./...

Launching the MCP Server

bash ./gqai serve --config .graphqlrc.yml

Executing CLI Diagnostics

bash ./gqai tools/invoke retrieve_all_sagas

Overview of GQAI

🤖 Rationale for gql-interface-adapter

gqai simplifies the transformation of a GraphQL API surface into a readily consumable toolset for sophisticated models — requiring zero manual coding or auxiliary infrastructure setup. Simply articulate your required operations; the agent interfacing layer materializes automatically.

📜 Licensing Terms

Licensed under the MIT License — feel free to fork, enhance, and integrate freely.

👋 Creator

Developed with dedication and an appreciation for automated systems by Stephen Spalding & <your-name-here>

WIKIPEDIA: XMLHttpRequest (XHR) is a standardized application programming interface implemented as a JavaScript object. Its methods facilitate the dispatching of HTTP requests from a web client environment (like a browser) to a remote web server. This capability allows client-side applications to initiate server communications subsequent to initial page load and subsequently receive asynchronous data back. XMLHttpRequest forms a core technological pillar of Ajax programming paradigms. Before Ajax's rise, page interaction relied predominantly on traditional hyperlink navigation and form submissions, frequently resulting in full-page refreshes.

== Lineage == The foundational concept underlying XMLHttpRequest was first conceptualized in 2000 by the development team behind Microsoft Outlook. This concept was subsequently materialized within the Internet Explorer 5 browser release (1999). However, the initial programmatic identifier used was not XMLHttpRequest; instead, developers utilized COM object instantiations: ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), universal support for the standardized XMLHttpRequest identifier was established across all major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Bodies === The World Wide Web Consortium (W3C) published its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft Level 2 specification followed on February 25, 2008, introducing features like event progress monitoring, support for cross-site resource sharing (CORS), and byte stream handling capabilities. By the close of 2011, the Level 2 enhancements were formally merged back into the primary specification document. Since late 2012, development authority has transitioned to the WHATWG, which maintains the living document utilizing Web IDL definitions.

== Operational Flow == Sending a network request using XMLHttpRequest typically involves a predefined sequence of programming steps.

1. Instantiate an XMLHttpRequest object via its constructor:
2. Invoke the "open" method to define the HTTP method type, specify the target Uniform Resource Identifier (URI), and select between synchronous or asynchronous execution mode:
3. For asynchronous operations, register an event handler function designed to be triggered upon changes to the request's state:
4. Initiate the transmission of the request using the "send" method:
5. Process state transitions within the registered event listener. Upon successful receipt of a response, the data is typically contained within the "responseText" property. When the object finalizes its processing, the state transitions to 4, signifying the "done" status. Beyond these core steps, XMLHttpRequest offers extensive capabilities for granular control over request transmission parameters and response consumption. Custom HTTP headers can be prepended to instruct the server on fulfillment expectations, and data payloads can be uploaded to the server by supplying them as arguments to the "send" invocation. The received data can be parsed directly from JSON format into native JavaScript objects or processed incrementally as data streams arrive, avoiding mandatory wait for the complete payload. Furthermore, requests can be terminated prematurely or configured with timeouts to enforce completion deadlines.

== Inter-Domain Communication ==

During the nascent stages of the World Wide Web's evolution, limitations quickly became apparent regarding the ability to initiate requests across different security domains (origins), which posed significant architectural hurdles for dynamic web applications.