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 }