mcp-server: Instructions file for Claude Code

CLAUDE.md

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

Essential Commands

Development Commands

# Install dependencies
npm ci

# Build the project (TypeScript compilation)
npm run build

# Start development server with auto-reload (no build required)
npm run dev:stdio   # For STDIO transport
npm run dev:shttp   # For Streamable HTTP transport

# Start production server (requires build)
npm run start:stdio  # For STDIO transport
npm run start:shttp  # For Streamable HTTP transport

Code Quality Commands

# Run formatter and linter check
npm run format

# Auto-fix formatting and linting issues
npm run format:fix

Debugging

# Debug with MCP inspector
npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node build/bin.js

# Or inspect streamable HTTP server
npx @modelcontextprotocol/inspector

Architecture Overview

This is a Model Context Protocol (MCP) server for Kontent.ai that enables AI models to interact with Kontent.ai's APIs through natural language. The project follows a modular architecture:

Core Components

1. Transport Layer (src/bin.ts, with the Streamable HTTP app built by src/app.ts): Single entry point supporting two transport protocols:

   • STDIO: Direct process communication (single-tenant only)
   • Streamable HTTP: Request-response based HTTP communication (supports multi-tenant)

2. Server Core (src/server.ts): Central server instance that:

   • Registers all available tools
   • Manages MCP server lifecycle
   • Coordinates tool execution

3. Tools Directory (src/tools/): Each tool is a separate module that:

   • Implements a specific Kontent.ai operation
   • Uses standardized error handling via errorHandler.ts
   • Returns responses using createMcpToolSuccessResponse
   • Must call get-patch-guide before any patch operation — the patch tool's own description must say "Always call get-patch-guide(entityType='…') first" with that exact "Always" emphasis. A weaker phrasing ("Call… first" without "Always") is regularly ignored by the agent in practice. All patch-* tool descriptions must use this exact phrasing — check for drift when adding or editing one.