contentstack-mcp

Instructions

Implementation Reference

• src/index.ts:934-1070 (handler)

  The handler function for the 'get_entries' tool. Constructs a Contentstack API URL with extensive query parameters for filtering, sorting, pagination, references, and more. Fetches entries and formats the response with summaries for large result sets.

  async ({
    content_type_uid,
    locale,
    query,
    include_count,
    skip,
    limit,
    include_reference,
    include_reference_content_type_uid,
    include_schema,
    include_global_field_schema,
    asc,
    desc,
    only,
    except,
    include_metadata,
    include_publish_details,
    include_owner,
  }) => {
    try {
      const url = new URL(`${API_BASE_URL}/content_types/${content_type_uid}/entries`)
  
      // Add query parameters if provided
      if (locale) {
        url.searchParams.append('locale', locale)
      }
  
      if (query) {
        url.searchParams.append('query', query)
      }
  
      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_reference && include_reference.length > 0) {
        url.searchParams.append('include[]', include_reference.join(','))
      }
  
      if (include_reference_content_type_uid) {
        url.searchParams.append('include_reference_content_type_uid', 'true')
      }
  
      if (include_schema) {
        url.searchParams.append('include_schema', 'true')
      }
  
      if (include_global_field_schema) {
        url.searchParams.append('include_global_field_schema', 'true')
      }
  
      if (asc) {
        url.searchParams.append('asc', asc)
      }
  
      if (desc) {
        url.searchParams.append('desc', desc)
      }
  
      if (only && only.length > 0) {
        url.searchParams.append('only[BASE][]', only.join(','))
      }
  
      if (except && except.length > 0) {
        url.searchParams.append('except[BASE][]', except.join(','))
      }
  
      if (include_metadata) {
        url.searchParams.append('include_metadata', 'true')
      }
  
      if (include_publish_details) {
        url.searchParams.append('include_publish_details', 'true')
      }
  
      if (include_owner) {
        url.searchParams.append('include_owner', 'true')
      }
  
      const response = await axios.get<EntriesResponse>(url.toString(), {
        headers: getHeaders(),
      })
  
      // Format the response
      let formattedResponse = ''
  
      if (include_count && response.data.count) {
        formattedResponse += `Total entries: ${response.data.count}\n\n`
      }
  
      formattedResponse += `Entries retrieved: ${response.data.entries.length}\n\n`
  
      if (response.data.entries.length > 0) {
        // For large result sets, show a summary instead of all data
        if (response.data.entries.length > 10) {
          formattedResponse += 'First 10 entries (showing UIDs):\n'
          for (let i = 0; i < 10; i++) {
            const entry = response.data.entries[i]
            formattedResponse += `${i + 1}. ${entry.uid} - ${entry.title || '[No title]'}\n`
          }
          formattedResponse += `\n(${response.data.entries.length - 10} more entries not shown)\n\n`
          formattedResponse += `Full response data:\n${JSON.stringify(response.data, null, 2)}`
        } else {
          formattedResponse += `Entries:\n${JSON.stringify(response.data.entries, null, 2)}`
        }
      } else {
        formattedResponse += 'No entries found matching the criteria.'
      }
  
      return {
        content: [
          {
            type: 'text',
            text: formattedResponse,
          },
        ],
      }
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error retrieving entries: ${handleError(error as ApiError)}`,
          },
        ],
        isError: true,
      }
    }
  },

• src/index.ts:911-933 (schema)

  Input schema using Zod for validating parameters to the get_entries tool, supporting comprehensive querying options.

  {
    content_type_uid: z.string().describe('Content type UID to fetch entries from'),
    locale: z.string().optional().describe("Locale code (e.g., 'en-us')"),
    query: z.string().optional().describe('Query in JSON format to filter entries'),
    include_count: z.boolean().optional().default(false).describe('Include total count of entries'),
    skip: z.number().optional().default(0).describe('Number of entries to skip (for pagination)'),
    limit: z.number().optional().default(100).describe('Number of entries to return (max 100)'),
    include_reference: z.array(z.string()).optional().describe('References to include'),
    include_reference_content_type_uid: z
      .boolean()
      .optional()
      .default(false)
      .describe('Include content type UIDs in references'),
    include_schema: z.boolean().optional().default(false).describe('Include content type schema'),
    include_global_field_schema: z.boolean().optional().default(false).describe('Include global field schema'),
    asc: z.string().optional().describe('Sort entries in ascending order by the specified field UID'),
    desc: z.string().optional().describe('Sort entries in descending order by the specified field UID'),
    only: z.array(z.string()).optional().describe('Include only specified top-level fields in the response'),
    except: z.array(z.string()).optional().describe('Exclude specified top-level fields from the response'),
    include_metadata: z.boolean().optional().default(false).describe('Include metadata in the response'),
    include_publish_details: z.boolean().optional().default(false).describe('Include publish details in the response'),
    include_owner: z.boolean().optional().default(false).describe('Include owner information in the response'),
  },

• src/types.ts:119-122 (schema)

  TypeScript interface defining the expected response structure from the Contentstack entries API, used in the handler.

  export interface EntriesResponse {
    entries: Entry[]
    count?: number
  }

• src/index.ts:908-909 (registration)

  Registration of the 'get_entries' tool on the MCP server.

  server.tool(
    'get_entries',