mcp4gql

Instructions

Implementation Reference

• src/server.ts:52-57 (registration)

  Registration of the 'executeGraphQLOperation' tool in the ListTools response, including name, description, and input schema reference.
  { 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 CallTool handler that routes calls to 'executeGraphQLOperation' to the handleExecution function after validation.
  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/tools/executor.ts:6-18 (schema)

  Zod schema definition for input validation of the 'executeGraphQLOperation' tool.
  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/tools/executor.ts:42-92 (handler)

  Main handler function for 'executeGraphQLOperation' tool that orchestrates input destructuring, GraphQL execution, error handling, and response formatting.
  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/graphqlClient.ts:28-129 (helper)

  Core helper function 'executeGraphQL' that performs the HTTP POST request to the GraphQL endpoint using axios, handles authentication, and manages various error conditions.
  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)) } ); } } }