contentstack-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Contentstack MCP Server is a Model Context Protocol server that integrates with Contentstack's Content Management API. It enables AI assistants like Claude to interact with Contentstack CMS through a standardized protocol.

Development Commands

# Install dependencies
npm install

# Development mode
npm run dev

# Build the project
npm run build

# Clean build artifacts
npm run clean

# Start the server (after building)
npm start

# Code Quality
npm run lint       # Check and fix code with Biome
npm run typecheck  # Type check with TypeScript

Architecture

The project is a TypeScript application structured around the Model Context Protocol (MCP):

1. Server Definition (src/index.ts): Creates and configures the MCP server with resources, tools, and prompts.

2. Type Definitions (src/types.ts): TypeScript interfaces for Contentstack API requests and responses.

3. Main Components:

   • Resources: URI-based endpoints to fetch content from Contentstack
   • Tools: Functions to perform operations on Contentstack content
   • Prompts: Guided workflows for content operations

4. Configuration:

   • The server requires Contentstack API credentials (API Key and Management Token)
   • Credentials are loaded from environment variables
   • Optional branch specification for multi-branch setups

5. Build System:

   • Uses esbuild (lib/build.js) to bundle the application
   • Outputs to dist/bundle.js

Environment Variables and CLI Options

Required environment variables:

• CONTENTSTACK_API_KEY: Your Contentstack stack API key
• CONTENTSTACK_MANAGEMENT_TOKEN: Management token with necessary permissions

Optional environment variables:

• CONTENTSTACK_BRANCH: Branch name (if using branches)

Command Line Usage

The server can be run directly via CLI with the following options: