contentstack-mcp

Instructions

Implementation Reference

• src/index.ts:1357-1442 (handler)

  Full inline implementation of the 'get_all_global_fields' tool handler, including registration, input schema (Zod), API call to Contentstack, response formatting, and error handling.

  server.tool(
    'get_all_global_fields',
    'Retrieves a list of all global fields, with options for pagination and including branch information.',
    {
      include_count: z.boolean().optional().default(false).describe('Include total count of global fields'),
      skip: z.number().optional().default(0).describe('Number of global fields to skip (for pagination)'),
      limit: z.number().optional().default(100).describe('Number of global fields to return (max 100)'),
      include_branch_info: z.boolean().optional().default(false).describe('Include branch information in response'),
    },
    async ({ include_count, skip, limit, include_branch_info }) => {
      try {
        const url = new URL(`${API_BASE_URL}/global_fields`)
  
        // Add query parameters if needed
        if (include_count) {
          url.searchParams.append('include_count', 'true')
        }
  
        if (skip > 0) {
          url.searchParams.append('skip', skip.toString())
        }
  
        if (limit !== 100) {
          url.searchParams.append('limit', limit.toString())
        }
  
        if (include_branch_info) {
          url.searchParams.append('include_branch_info', 'true')
        }
  
        const response = await axios.get<GlobalFieldsResponse>(url.toString(), {
          headers: getHeaders(),
        })
  
        // Format the response
        let formattedResponse = ''
  
        if (include_count && response.data.count) {
          formattedResponse += `Total global fields: ${response.data.count}\n\n`
        }
  
        formattedResponse += `Global fields retrieved: ${response.data.global_fields.length}\n\n`
  
        if (response.data.global_fields.length > 0) {
          // For large result sets, show a summary
          if (response.data.global_fields.length > 10) {
            formattedResponse += 'First 10 global fields:\n'
            for (let i = 0; i < 10; i++) {
              const globalField = response.data.global_fields[i]
              formattedResponse += `${i + 1}. ${globalField.uid} - ${globalField.title}\n`
            }
            formattedResponse += `\n(${response.data.global_fields.length - 10} more global fields not shown)\n\n`
          } else {
            formattedResponse += 'Global fields:\n'
            response.data.global_fields.forEach((globalField, index) => {
              formattedResponse += `${index + 1}. ${globalField.uid} - ${globalField.title}\n`
            })
            formattedResponse += '\n'
          }
  
          formattedResponse += `Full response data:\n${JSON.stringify(response.data, null, 2)}`
        } else {
          formattedResponse += 'No global fields found.'
        }
  
        return {
          content: [
            {
              type: 'text',
              text: formattedResponse,
            },
          ],
        }
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error retrieving global fields: ${handleError(error as ApiError)}`,
            },
          ],
          isError: true,
        }
      }
    },
  )

• src/types.ts:128-131 (schema)

  TypeScript interface defining the response structure for global fields API.

  export interface GlobalFieldsResponse {
    global_fields: GlobalField[]
    count?: number
  }

• src/index.ts:36-52 (helper)

  Helper function to generate authentication headers used in the API request.

  const getHeaders = () => {
    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
      api_key: API_KEY,
    }
  
    // Use management token
    if (MANAGEMENT_TOKEN) {
      headers.authorization = MANAGEMENT_TOKEN
    }
  
    // Include branch header if specified
    if (BRANCH) {
      headers.branch = BRANCH
    }
  
    return headers

• src/index.ts:63-70 (helper)

  Helper function to format error messages from API responses, used in error handling.

  const handleError = (error: ApiError): string => {
    if (error.response) {
      return `API Error: ${error.response.status} - ${JSON.stringify(error.response.data)}`
    }
    if (error.request) {
      return `No response received: ${error.request}`
    }
    return `Error: ${error.message}`