mcp4gql

Instructions

Implementation Reference

• src/tools/executor.ts:42-92 (handler)

  The handleExecution function that implements the core logic for executing the GraphQL operation tool, including input destructuring, calling the GraphQL client, error handling, and returning the response.
  export async function handleExecution( input: z.infer<typeof ExecutorSchemaInput> ): Promise<z.infer<typeof ExecutorSchemaOutput>> { const { query, variables, operationName } = input; try { console.error(`Executing GraphQL query: ${operationName || "unnamed"}...`); const response = await executeGraphQL<z.infer<typeof ExecutorSchemaOutput>>( query, variables, operationName ); // GraphQL endpoints often return 200 OK even if there are query errors. // These are included in the 'errors' array in the response body. if (response.errors && response.errors.length > 0) { const errorMessages = response.errors.map((e) => e.message).join("; "); console.error( `GraphQL query ${ operationName || "unnamed" } returned errors: ${errorMessages}`, response.errors ); // We return the full response including data and errors as per the MCP flow // The client consuming the MCP tool will decide how to handle the errors field. // No McpError is thrown here unless the request itself failed (handled in executeGraphQL) } console.error(`GraphQL query ${operationName || "unnamed"} executed.`); return response; // Return the full response { data?: ..., errors?: ... } } catch (error) { // This catches errors thrown by executeGraphQL (network, HTTP errors, etc.) console.error( `Error executing GraphQL query ${operationName || "unnamed"}:`, error ); if (error instanceof McpError) { // Re-throw McpErrors directly throw error; } // Wrap unexpected errors throw new McpError( ErrorCode.InternalError, `An unexpected error occurred while executing the GraphQL query '${ operationName || "unnamed" }'.`, { cause: error as Error } ); } }
• src/tools/executor.ts:6-18 (schema)

  Zod schema defining the input parameters for the executeGraphQLOperation tool: query (required string), variables (optional record), operationName (optional string).
  export const ExecutorSchemaInput = z.object({ query: z.string().describe("The GraphQL query string to execute."), variables: z .record(z.unknown()) .optional() .describe("An optional object containing variables for the query."), operationName: z .string() .optional() .describe( "An optional name for the operation, if the query contains multiple operations." ), });
• src/server.ts:52-57 (registration)

  Registration of the executeGraphQLOperation tool in the ListTools response, including name, description, and inputSchema derived from ExecutorSchemaInput.
  { name: "executeGraphQLOperation", description: "Executes an arbitrary GraphQL query or mutation against the target API. Use introspectGraphQLSchema first to understand the available operations.", inputSchema: executeInputSchema, },
• src/server.ts:87-92 (registration)

  Dispatch logic in the CallTool handler switch statement that validates input with ExecutorSchemaInput and calls handleExecution for executeGraphQLOperation.
  case "executeGraphQLOperation": // Validate arguments using the Zod schema const validatedArgs = ExecutorSchemaInput.parse(args); console.error(`Calling handler for ${name}`); result = await handleExecution(validatedArgs); break;
• src/graphqlClient.ts:28-129 (helper)

  The executeGraphQL helper function that performs the actual HTTP POST request to the GraphQL endpoint using axios, handles authentication, timeouts, and various error cases with McpError.
  export async function executeGraphQL<T = any>( query: string, variables?: Record<string, any>, operationName?: string ): Promise<GraphQLResponse<T>> { const { graphqlEndpoint, authToken } = config; if (!graphqlEndpoint) { // Use PascalCase for ErrorCode members throw new McpError( ErrorCode.InternalError, "GraphQL endpoint URL is not configured." ); } // We check authToken existence in config.ts, assume it's present if needed or proceed if not. const headers: Record<string, string> = { "Content-Type": "application/json", Accept: "application/json", }; if (authToken) { headers["Authorization"] = `Bearer ${authToken}`; } try { const response = await axios.post<GraphQLResponse<T>>( graphqlEndpoint, { query, variables, ...(operationName && { operationName }), }, { headers, timeout: 30000, // 30 second timeout } ); // Axios considers 2xx successful, return the body directly // The caller should check for response.data.errors return response.data; } catch (error: any) { // Use the imported isAxiosError type guard if (error.response) { // Now variable 'error' is narrowed to AxiosError type const statusCode = error.response?.status; const responseData = error.response?.data as any; const errorMessageBase = `GraphQL request failed: ${error.message}`; let detailedMessage = errorMessageBase; if (responseData?.errors?.[0]?.message) { detailedMessage = `${errorMessageBase} - ${responseData.errors[0].message}`; } if (statusCode === 401) { // Use PascalCase for ErrorCode members throw new McpError( ErrorCode.InvalidRequest, "Authentication failed. Check your AUTH_TOKEN.", { cause: error } ); } if (statusCode === 403) { // Use PascalCase for ErrorCode members throw new McpError( ErrorCode.InvalidRequest, "Permission denied for GraphQL operation.", { cause: error } ); } if (statusCode && statusCode >= 400 && statusCode < 500) { // Use PascalCase for ErrorCode members throw new McpError(ErrorCode.InvalidRequest, detailedMessage, { cause: error, }); } // Includes 5xx errors and network errors (statusCode is undefined) // Use PascalCase for ErrorCode members throw new McpError(ErrorCode.InternalError, detailedMessage, { cause: error, }); } else if (error instanceof Error) { console.error("Unexpected error during GraphQL request:", error); // Use PascalCase for ErrorCode members throw new McpError( ErrorCode.InternalError, `An unexpected error occurred: ${error.message}`, { cause: error } ); } else { console.error( "Unexpected non-error thrown during GraphQL request:", error ); throw new McpError( ErrorCode.InternalError, "An unexpected non-error value was thrown during the GraphQL request.", { cause: new Error(String(error)) } ); } } }