GraphQL Plugin

Relevant source files

• packages/core/sdk/src/auth-tool-failure.ts
• packages/plugins/google/src/react/AddGoogleSource.tsx
• packages/plugins/graphql/src/api/group.ts
• packages/plugins/graphql/src/api/handlers.ts
• packages/plugins/graphql/src/react/AddGraphqlSource.tsx
• packages/plugins/graphql/src/react/atoms.ts
• packages/plugins/graphql/src/sdk/errors.ts
• packages/plugins/graphql/src/sdk/introspect.ts
• packages/plugins/graphql/src/sdk/invoke.ts
• packages/plugins/graphql/src/sdk/types.ts
• packages/plugins/mcp/src/react/AddMcpSource.tsx
• packages/plugins/mcp/src/react/atoms.ts
• packages/plugins/microsoft/src/react/AddMicrosoftSource.tsx
• packages/plugins/openapi/src/react/AddOpenApiSource.tsx
• packages/plugins/openapi/src/react/atoms.ts
• packages/plugins/openapi/src/react/index.ts
• packages/plugins/openapi/src/sdk/config.ts
• packages/plugins/openapi/src/sdk/errors.ts
• packages/plugins/openapi/src/sdk/spec-blob.test.ts
• packages/plugins/openapi/src/sdk/upstream-failures.test.ts

The GraphQL plugin enables the Executor system to interface with GraphQL APIs by introspecting their schemas, materializing fields into executable tools, and handling complex operation generation. It supports advanced features like custom selection sets and flexible authentication mapping via headers and query parameters.

Overview and Data Flow

The GraphQL plugin follows a lifecycle of Introspection → Extraction → Invocation. Unlike the OpenAPI plugin which often deals with static files, the GraphQL plugin primarily interacts with live endpoints to derive its tool definitions.

System Architecture Diagram

This diagram bridges the Natural Language concepts to the specific Code Entities responsible for the GraphQL lifecycle.

"GraphQL Integration Lifecycle"

Sources: packages/plugins/graphql/src/react/AddGraphqlSource.tsx104-129 packages/plugins/graphql/src/api/handlers.ts33-52 packages/plugins/graphql/src/sdk/introspect.ts232-237 packages/plugins/graphql/src/sdk/invoke.ts59-65

Schema Introspection and Extraction

The plugin performs a standard GraphQL introspection query to discover available types, fields, and arguments.

Introspection Logic

The introspect function in <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/introspect.ts#L232-L237" min=232 max=237 file-path="packages/plugins/graphql/src/sdk/introspect.ts">Hii</FileRef> sends a comprehensive INTROSPECTION_QUERY <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/introspect.ts#L10-L78" min=10 max=78 file-path="packages/plugins/graphql/src/sdk/introspect.ts">Hii</FileRef> to the target endpoint. This query retrieves:

• Query and Mutation types: Identifying the entry points for the API.
• Full Type System: Including scalars, objects, enums, and input objects.
• Field Metadata: Descriptions, arguments, and deprecation status.

Field Extraction

Once the schema is retrieved, the plugin materializes it into ExtractedField objects <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/types.ts#L30-L41" min=30 max=41 file-path="packages/plugins/graphql/src/sdk/types.ts">Hii</FileRef>. Each field includes:

• fieldName: The name of the GraphQL field (e.g., createUser).
• kind: Either query or mutation <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/types.ts#L15-L16" min=15 max=16 file-path="packages/plugins/graphql/src/sdk/types.ts">Hii</FileRef>.
• inputSchema: A JSON Schema generated from the GraphQL arguments to allow the Executor engine to validate inputs.
• returnTypeName: The GraphQL type returned by the field.

Sources: packages/plugins/graphql/src/sdk/introspect.ts10-78 packages/plugins/graphql/src/sdk/types.ts30-41

Operation Materialization and Invocation

When a tool is called, the plugin must transform the tool arguments back into a valid GraphQL operation.

Operation Binding

The OperationBinding struct <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/types.ts#L55-L71" min=55 max=71 file-path="packages/plugins/graphql/src/sdk/types.ts">Hii</FileRef> stores the minimal data needed for invocation, including an operationPrefix and operationSuffix.

Dynamic Selection Input

A unique feature of the GraphQL plugin is the select control input. While standard tools have fixed outputs, GraphQL tools allow the caller to specify which fields to return by passing a select argument.

• The effectiveOperationString function <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/invoke.ts#L31-L41" min=31 max=41 file-path="packages/plugins/graphql/src/sdk/invoke.ts">Hii</FileRef> checks for a select string in the arguments.
• If present, it splices the custom selection into the operation: ${operationPrefix} { ${customSelect} }${operationSuffix}.
• If absent, it falls back to a default scalar-leaf selection stored in operationString.

Invocation Flow

The invoke function <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/invoke.ts#L59-L143" min=59 max=143 file-path="packages/plugins/graphql/src/sdk/invoke.ts">Hii</FileRef> performs the following steps:

1. Telemetry: Annotates the current span with endpoint and operation details <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/invoke.ts#L70-L78" min=70 max=78 file-path="packages/plugins/graphql/src/sdk/invoke.ts">Hii</FileRef>.
2. Variable Mapping: Maps tool arguments to GraphQL variables defined in the operation <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/invoke.ts#L81-L91" min=81 max=91 file-path="packages/plugins/graphql/src/sdk/invoke.ts">Hii</FileRef>.
3. HTTP Request: Sends a POST request with application/json content type, containing the query and variables <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/invoke.ts#L98-L104" min=98 max=104 file-path="packages/plugins/graphql/src/sdk/invoke.ts">Hii</FileRef>.
4. Header Injection: Applies resolved authentication headers <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/invoke.ts#L106-L108" min=106 max=108 file-path="packages/plugins/graphql/src/sdk/invoke.ts">Hii</FileRef>.

Sources: packages/plugins/graphql/src/sdk/types.ts55-71 packages/plugins/graphql/src/sdk/invoke.ts31-41 packages/plugins/graphql/src/sdk/invoke.ts59-143

Authentication Handling

The GraphQL plugin uses the shared @executor-js/sdk/http-auth vocabulary but extends it for GraphQL-specific needs.

Method Kind	Implementation	Code Reference
none	No credentials sent; used for open endpoints.	<FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/types.ts#L105-L105" min=105 file-path="packages/plugins/graphql/src/sdk/types.ts">Hii</FileRef>
apikey	Supports multiple placements in headers or queryParams.	<FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/types.ts#L106-L106" min=106 file-path="packages/plugins/graphql/src/sdk/types.ts">Hii</FileRef>
oauth2	Injects an OAuth access token as a bearer header.	<FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/types.ts#L94-L102" min=94 max=102 file-path="packages/plugins/graphql/src/sdk/types.ts">Hii</FileRef>

The authenticationTemplate is managed via the AuthMethodListEditor in the UI, which allows users to define how secrets (like API keys) are mapped to specific header names or query parameters <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/react/AddGraphqlSource.tsx#L143-L148" min=143 max=148 file-path="packages/plugins/graphql/src/react/AddGraphqlSource.tsx">Hii</FileRef>.

Sources: packages/plugins/graphql/src/sdk/types.ts91-109 packages/plugins/graphql/src/react/AddGraphqlSource.tsx143-148

React UI: AddGraphqlSource

The AddGraphqlSource component <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/react/AddGraphqlSource.tsx#L41-L164" min=41 max=164 file-path="packages/plugins/graphql/src/react/AddGraphqlSource.tsx">Hii</FileRef> provides the user interface for registering a new GraphQL integration.

Registration Logic

1. Identity Tracking: Uses useIntegrationIdentity to derive a slug and display name from the URL <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/react/AddGraphqlSource.tsx#L48-L50" min=48 max=50 file-path="packages/plugins/graphql/src/react/AddGraphqlSource.tsx">Hii</FileRef>.
2. Slug Collision Guard: Uses useSlugAlreadyExists to prevent overwriting existing integrations <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/react/AddGraphqlSource.tsx#L92-L92" min=92 file-path="packages/plugins/graphql/src/react/AddGraphqlSource.tsx">Hii</FileRef>.
3. Auth Configuration: The AuthMethodListEditor seeds the authenticationTemplate <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/react/AddGraphqlSource.tsx#L63-L71" min=63 max=71 file-path="packages/plugins/graphql/src/react/AddGraphqlSource.tsx">Hii</FileRef>.
4. Optimistic Submission: Calls addGraphqlIntegrationOptimistic (an Effect-based atom) to register the source with the backend <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/react/AddGraphqlSource.tsx#L109-L120" min=109 max=120 file-path="packages/plugins/graphql/src/react/AddGraphqlSource.tsx">Hii</FileRef>.

"Add Source State Machine"

Sources: packages/plugins/graphql/src/react/AddGraphqlSource.tsx94-130

Error Handling

The plugin defines specific error classes to provide granular feedback during the integration process:

• GraphqlIntrospectionError: Thrown when the __schema query fails or the response is malformed <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/errors.ts" undefined file-path="packages/plugins/graphql/src/sdk/errors.ts">Hii</FileRef>.
• GraphqlExtractionError: Thrown when the plugin cannot convert the GraphQL schema into tool definitions.
• GraphqlInvocationError: Thrown during tool execution if the network request fails or the upstream returns GraphQL errors <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/sdk/invoke.ts#L113-L117" min=113 max=117 file-path="packages/plugins/graphql/src/sdk/invoke.ts">Hii</FileRef>.

These errors are mapped to HTTP status codes (e.g., 400 for introspection/extraction errors) in the API layer using HttpApiGroup annotations <FileRef file-url="https://github.com/UsefulSoftwareCo/executor/blob/fd4fb02f/packages/plugins/graphql/src/api/group.ts#L71-L74" min=71 max=74 file-path="packages/plugins/graphql/src/api/group.ts">Hii</FileRef>.

Sources: packages/plugins/graphql/src/sdk/invoke.ts110-119 packages/plugins/graphql/src/api/group.ts71-90