Contentful GraphQL MCP Server

Instructions

Implementation Reference

• src/handlers/graphql-handlers.ts:736-897 (handler)

  Main handler function `executeQuery` that executes the provided GraphQL query against Contentful's GraphQL API using delivery token. Supports schema validation if cached, handles variables, environment overrides, and returns formatted ToolResponse with JSON data or errors.

  executeQuery: async (args: GraphQLQueryArgs): Promise<ToolResponse> => {
    try {
      // Get values from environment variables with optional overrides
      const spaceId = args.spaceId || process.env.SPACE_ID
      const environmentId = args.environmentId || process.env.ENVIRONMENT_ID || "master"
      const accessToken = process.env.CONTENTFUL_DELIVERY_ACCESS_TOKEN
  
      if (!spaceId) {
        return {
          content: [
            {
              type: "text",
              text: "Space ID is required (set SPACE_ID environment variable or provide spaceId parameter)",
            },
          ],
          isError: true,
        }
      }
  
      if (!accessToken) {
        return {
          content: [
            {
              type: "text",
              text: "Content Delivery API (CDA) token is required for GraphQL queries (set CONTENTFUL_DELIVERY_ACCESS_TOKEN environment variable)",
            },
          ],
          isError: true,
        }
      }
  
      // Validate the query against the schema if available
      if (graphqlSchema) {
        try {
          const queryDocument = parse(args.query)
          const validationErrors = validate(graphqlSchema, queryDocument)
  
          if (validationErrors.length > 0) {
            return {
              content: [
                {
                  type: "text",
                  text: JSON.stringify(
                    {
                      errors: validationErrors.map((error) => ({ message: error.message })),
                    },
                    null,
                    2,
                  ),
                },
              ],
              isError: true,
            }
          }
        } catch (parseError) {
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(
                  {
                    errors: [{ message: `GraphQL query parsing error: ${parseError}` }],
                  },
                  null,
                  2,
                ),
              },
            ],
            isError: true,
          }
        }
      } else {
        console.warn("GraphQL schema not available for validation")
      }
  
      // Execute the query against the Contentful GraphQL API
      const endpoint = `https://graphql.contentful.com/content/v1/spaces/${spaceId}/environments/${environmentId}`
  
      const response = await fetch(endpoint, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify({
          query: args.query,
          variables: args.variables || {},
        }),
      })
  
      // Handle HTTP error responses
      if (!response.ok) {
        const errorText = await response.text()
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  errors: [{ message: `HTTP Error ${response.status}: ${errorText}` }],
                },
                null,
                2,
              ),
            },
          ],
          isError: true,
        }
      }
  
      const result = (await response.json()) as GraphQLExecuteResponse
  
      console.error("GraphQL response:", JSON.stringify(result))
  
      // Check for GraphQL errors
      if (result.errors) {
        const errorResponse = {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  errors: result.errors,
                },
                null,
                2,
              ),
            },
          ],
          isError: true,
        }
        console.error("Returning error response:", JSON.stringify(errorResponse))
        return errorResponse
      }
  
      // Return the successful result
      const successResponse = {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      }
      console.error("Returning success response:", JSON.stringify(successResponse))
      return successResponse
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                errors: [
                  {
                    message: `Error executing GraphQL query: ${error instanceof Error ? error.message : String(error)}`,
                  },
                ],
              },
              null,
              2,
            ),
          },
        ],
        isError: true,
      }
    }

• src/types/tools.ts:88-107 (schema)

  Tool schema definition for 'graphql_query' including name, description, and inputSchema with required 'query' string and optional 'variables' object, plus env overrides.

  GRAPHQL_QUERY: {
    name: "graphql_query",
    description:
      "IMPORTANT: Before using this tool, you MUST first use graphql_list_content_types and graphql_get_content_type_schema to understand the available content types and their structure. Execute a GraphQL query against the Contentful GraphQL API. This tool allows you to use Contentful's powerful GraphQL interface to retrieve content in a more flexible and efficient way than REST API calls. The space ID and CDA token are automatically retrieved from environment variables.",
    inputSchema: getOptionalEnvProperties({
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "The GraphQL query string to execute (must be a valid GraphQL query)",
        },
        variables: {
          type: "object",
          description: "Optional variables for the GraphQL query",
          additionalProperties: true,
        },
      },
      required: ["query"],
    }),
  },

• src/index.ts:118-131 (registration)

  Registration of 'graphql_query' tool to graphqlHandlers.executeQuery in the main stdio server's getHandler function.

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  function getHandler(name: string): ((args: any) => Promise<any>) | undefined {
    const cdaOnlyHandlers = {
      // Only GraphQL operations are allowed with just a CDA token
      graphql_query: graphqlHandlers.executeQuery,
      graphql_list_content_types: graphqlHandlers.listContentTypes,
      graphql_get_content_type_schema: graphqlHandlers.getContentTypeSchema,
      graphql_get_example: graphqlHandlers.getExample,
      smart_search: graphqlHandlers.smartSearch,
      build_search_query: graphqlHandlers.buildSearchQuery,
    }
  
    return cdaOnlyHandlers[name as keyof typeof cdaOnlyHandlers]
  }

• src/transports/streamable-http.ts:319-337 (registration)

  Registration of 'graphql_query' tool to graphqlHandlers.executeQuery in the StreamableHTTP server's getHandler function.

  private getHandler(name: string):
    | ((args: Record<string, unknown>) => Promise<{
        content?: Array<{ type: string; text: string }>
        isError?: boolean
        message?: string
      }>)
    | undefined {
    // Determine which authentication methods are available
    const cdaOnlyHandlers = {
      // Only GraphQL operations are allowed with just a CDA token
      graphql_query: graphqlHandlers.executeQuery,
      graphql_list_content_types: graphqlHandlers.listContentTypes,
      graphql_get_content_type_schema: graphqlHandlers.getContentTypeSchema,
      graphql_get_example: graphqlHandlers.getExample,
    }
  
    // @ts-expect-error - The exact parameter and return types don't match, but they work at runtime
    return cdaOnlyHandlers[name as keyof typeof cdaOnlyHandlers]
  }

• src/handlers/graphql-handlers.ts:266-271 (schema)

  TypeScript interface defining input arguments for the GraphQL query handler.

  export interface GraphQLQueryArgs {
    spaceId?: string // Optional override for environment variable
    environmentId?: string // Optional override for environment variable
    query: string
    variables?: Record<string, any>
  }