MCP Fetch

Instructions

Implementation Reference

• src/tools/graphql.ts:65-100 (handler)

  Main GraphQL tool handler function that switches between 'execute' and 'introspect' actions, delegating to respective helper functions with comprehensive error handling.

  export default async function graphql({ action }: InferSchema<typeof schema>) {
    try {
      switch (action.type) {
        case "execute":
          return await executeGraphQL(
            action.endpoint,
            action.query,
            action.variables,
            action.headers,
            action.operationName,
            action.timeout
          )
  
        case "introspect":
          return await introspectGraphQL(
            action.endpoint,
            action.headers || {},
            action.action,
            action.typeName,
            action.useCache,
            action.cacheTTL
          )
  
        default:
          return JSON.stringify({
            success: false,
            error: "Invalid action type",
          }, null, 2)
      }
    } catch (error) {
      return JSON.stringify({
        success: false,
        error: error instanceof Error ? error.message : "Unknown error occurred",
      }, null, 2)
    }
  }

• src/tools/graphql.ts:7-50 (schema)

  Zod schema defining discriminated union for 'execute' (query/mutation with vars, headers) and 'introspect' (schema actions with cache) parameters.

  export const schema = {
    action: z.discriminatedUnion("type", [
      // GraphQL execution action
      z.object({
        type: z.literal("execute"),
        endpoint: z.string().describe("The GraphQL endpoint URL"),
        query: z.string().describe("The GraphQL query or mutation string"),
        variables: z.record(z.any())
          .optional()
          .describe("Variables to pass to the GraphQL query/mutation"),
        headers: z.record(z.string())
          .optional()
          .describe("HTTP headers to include in the request (e.g., authorization tokens)"),
        operationName: z.string()
          .optional()
          .describe("Name of the operation to execute (useful when query contains multiple operations)"),
        timeout: z.number()
          .optional()
          .default(30000)
          .describe("Request timeout in milliseconds. Defaults to 30 seconds"),
      }),
      // GraphQL introspection action
      z.object({
        type: z.literal("introspect"),
        endpoint: z.string().describe("The GraphQL endpoint URL to introspect"),
        headers: z.record(z.string())
          .optional()
          .describe("HTTP headers to include in the request (e.g., authorization tokens)"),
        action: z.enum(["full-schema", "list-operations", "get-type"])
          .describe("What to fetch: full-schema gets the complete schema, list-operations lists available queries/mutations, get-type gets a specific type definition"),
        typeName: z.string()
          .optional()
          .describe("The name of the type to fetch (required when action is 'get-type')"),
        useCache: z.boolean()
          .optional()
          .default(true)
          .describe("Whether to use cached schema if available"),
        cacheTTL: z.number()
          .optional()
          .default(300000)
          .describe("Cache time-to-live in milliseconds. Defaults to 5 minutes"),
      }),
    ]).describe("The action to perform with GraphQL"),
  }

• src/tools/graphql.ts:53-62 (registration)

  Tool metadata registration exporting name 'graphql', description, and annotations.

  export const metadata: ToolMetadata = {
    name: "graphql",
    description: "Execute GraphQL queries and mutations with support for variables and custom headers",
    annotations: {
      title: "GraphQL Client",
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
    },
  }

• src/utils/graphql/execute.ts:4-106 (helper)

  Core helper for executing GraphQL queries/mutations using graphql-request, with timeout, detailed errors, operation type detection, and sensitive header masking.

  export async function executeGraphQL(
    endpoint: string,
    query: string,
    variables?: Record<string, any>,
    headers?: Record<string, string>,
    operationName?: string,
    timeout: number = 30000
  ): Promise<string> {
    try {
      // Validate query syntax
      const document = gql`${query}`
  
      // Create GraphQL client with configuration
      const client = new GraphQLClient(endpoint, {
        headers: headers || {},
      })
  
      // Execute the GraphQL request
      const startTime = Date.now()
  
      // Set up timeout if specified
      let timeoutId: NodeJS.Timeout | undefined
      const timeoutPromise = timeout ? new Promise((_, reject) => {
        timeoutId = setTimeout(() => reject(new Error(`Request timed out after ${timeout}ms`)), timeout)
      }) : null
  
      // Race between request and timeout
      const data = await (timeoutPromise
        ? Promise.race([
          client.request(document, variables || {}),
          timeoutPromise
        ])
        : client.request(document, variables || {}))
  
      const responseTime = Date.now() - startTime
  
      // Clear timeout if set
      if (timeoutId) clearTimeout(timeoutId)
  
      // Parse operation type from query
      const operationType = detectOperationType(query)
  
      return JSON.stringify({
        success: true,
        data,
        operationType,
        responseTime: `${responseTime}ms`,
        request: {
          endpoint,
          operationName,
          variables: variables || {},
          headers: maskSensitiveHeaders(headers)
        }
      }, null, 2)
  
    } catch (error) {
      // Handle different error types
      let errorDetails: any = {
        success: false,
        error: "Unknown error occurred",
        errorType: "UnknownError",
      }
  
      if (error instanceof Error) {
        // GraphQL errors from graphql-request
        if ('response' in error && error.response) {
          const graphqlError = error as any
          errorDetails = {
            success: false,
            errorType: "GraphQLError",
            errors: graphqlError.response.errors || [],
            data: graphqlError.response.data || null,
            status: graphqlError.response.status,
            headers: graphqlError.response.headers,
          }
        }
        // Network or other errors
        else {
          errorDetails.error = error.message
  
          if (error.message.includes('timeout')) {
            errorDetails.errorType = "TimeoutError"
            errorDetails.error = `Request timed out after ${timeout}ms`
          } else if (error.message.includes('Network') || error.message.includes('fetch')) {
            errorDetails.errorType = "NetworkError"
          } else if (error.message.includes('Syntax Error')) {
            errorDetails.errorType = "SyntaxError"
            errorDetails.error = "Invalid GraphQL query syntax"
          }
        }
      }
  
      // Add request details to error response
      errorDetails.request = {
        endpoint,
        operationName,
        variables: variables || {},
        headers: maskSensitiveHeaders(headers)
      }
  
      return JSON.stringify(errorDetails, null, 2)
    }
  }

• src/utils/graphql/introspect.ts:151-197 (helper)

  Core helper for GraphQL introspection supporting full schema, operation lists, type details with schema caching.

  export async function introspectGraphQL(
    endpoint: string,
    headers: Record<string, string> = {},
    action: string,
    typeName?: string,
    useCache: boolean = true,
    cacheTTL: number = 300000
  ): Promise<string> {
    try {
      // Get schema (from cache or fetch)
      const introspectionData = await getSchema(endpoint, headers, useCache, cacheTTL)
  
      // Build schema from introspection result
      const schema = buildClientSchema(introspectionData)
  
      switch (action) {
        case "full-schema":
          return handleFullSchema(schema)
  
        case "list-operations":
          return handleListOperations(schema)
  
        case "get-type":
          if (!typeName) {
            return JSON.stringify({
              success: false,
              error: "typeName is required when action is 'get-type'",
            }, null, 2)
          }
          return handleGetType(schema, typeName)
  
        default:
          return JSON.stringify({
            success: false,
            error: `Unknown action: ${action}`,
          }, null, 2)
      }
  
    } catch (error) {
      return JSON.stringify({
        success: false,
        error: error instanceof Error ? error.message : "Unknown error occurred",
        errorType: error instanceof Error && error.message.includes("Network") ? "NetworkError" : "IntrospectionError",
        endpoint,
      }, null, 2)
    }
  }