Contentful GraphQL MCP Server

Instructions

Implementation Reference

• src/handlers/graphql-handlers.ts:632-733 (handler)

  The handler function `getExample` that generates and returns example GraphQL queries for a specified content type based on its schema.

    getExample: async (args: GetGraphQLExampleArgs): 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"
  
        // First get the schema
        const schemaResult = await graphqlHandlers.getContentTypeSchema({
          contentType: args.contentType,
          spaceId,
          environmentId,
        })
  
        if (schemaResult.isError) {
          return schemaResult
        }
  
        // Parse the schema from the result
        const schemaData = JSON.parse(schemaResult.content[0].text)
  
        // Generate a query for collection
        const isCollection = schemaData.contentType.endsWith("Collection")
        const contentTypeName = isCollection
          ? schemaData.contentType
          : schemaData.contentType.replace(/^[A-Z]/, (c: string) => c.toLowerCase())
        const collectionName = isCollection ? contentTypeName : `${contentTypeName}Collection`
        const singularName = isCollection
          ? contentTypeName.replace("Collection", "")
          : contentTypeName
  
        // Get top-level scalar fields
        const scalarFields = schemaData.fields
          .filter((field: any) => isScalarType(field.type))
          .map((field: any) => field.name)
  
        // Get reference fields if requested
        const referenceFields = args.includeRelations
          ? schemaData.fields
              .filter((field: any) => isReferenceType(field.type))
              .map((field: any) => ({
                name: field.name,
                type: field.type.replace("!", ""),
              }))
          : []
  
        // Build the example query
        let exampleQuery = `# Example query for ${schemaData.contentType}
  query {
    ${collectionName}(limit: 5) {
      items {
  ${scalarFields.map((field: string) => `      ${field}`).join("\n")}`
  
        if (referenceFields.length > 0) {
          exampleQuery += `\n
        # Related content references
  ${referenceFields
    .map(
      (field: any) => `      ${field.name} {
          ... on ${field.type} {
            # Add fields you want from ${field.type} here
          }
        }`,
    )
    .join("\n")}`
        }
  
        exampleQuery += `\n    }
    }
  }
  
  # You can also query a single item by ID
  query GetSingle${singularName}($id: String!) {
    ${singularName}(id: $id) {
  ${scalarFields.map((field: string) => `    ${field}`).join("\n")}
    }
  }
  
  # Variables for the above query would be:
  # {
  #   "id": "your-entry-id-here"
  # }`
  
        return {
          content: [
            {
              type: "text",
              text: exampleQuery,
            },
          ],
        }
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error generating example query: ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
          isError: true,
        }
      }
    },

• src/types/tools.ts:67-86 (schema)

  The tool schema definition for 'graphql_get_example', including input schema with properties like contentType and includeRelations.

  GRAPHQL_GET_EXAMPLE: {
    name: "graphql_get_example",
    description:
      "IMPORTANT: Use this tool AFTER using graphql_get_content_type_schema to see example GraphQL queries for a specific content type. Learning from these examples will help you construct valid queries. The space ID and CDA token are automatically retrieved from environment variables.",
    inputSchema: getOptionalEnvProperties({
      type: "object",
      properties: {
        contentType: {
          type: "string",
          description: "The name of the content type for the example query",
        },
        includeRelations: {
          type: "boolean",
          description:
            "Whether to include related content types in the example (defaults to false)",
        },
      },
      required: ["contentType"],
    }),
  },

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

  Registration of the tool name 'graphql_get_example' to the handler graphqlHandlers.getExample in the main server 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 the tool name 'graphql_get_example' to the handler in the StreamableHTTP transport'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:26-31 (schema)

  TypeScript interface defining the input arguments for the getExample handler.

  export interface GetGraphQLExampleArgs {
    contentType: string
    includeRelations?: boolean
    spaceId?: string // Optional override for environment variable
    environmentId?: string // Optional override for environment variable
  }