Skip to content

CLAUDE.md

Latest commit

 

History

History
114 lines (83 loc) · 4.04 KB

CLAUDE.md

File metadata and controls

114 lines (83 loc) · 4.04 KB

CLAUDE.md

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

Development Commands

  • npm run build - Compile TypeScript to build/ directory and make executable
  • npm run build:watch - Build with watch mode for development
  • npm run start - Start the compiled server from build/index.js
  • npm run dev - Run directly with ts-node for development
  • npm run dev:watch - Run with nodemon for hot reload during development

Debugging

Enable detailed logging via environment variables:

# Log levels: ERROR, WARN, INFO, DEBUG, TRACE
MCP_LOG_LEVEL=DEBUG npm run dev

# Enable/disable specific features
MCP_ENABLE_REQUEST_TRACKING=true
MCP_ENABLE_PERFORMANCE_MONITORING=true
MCP_SANITIZE_DATA=true
MCP_MAX_LOG_LENGTH=10000
MCP_INCLUDE_STACK_TRACE=true

# Enable MCP SDK debug logging
DEBUG=mcp:* npm run dev

Testing with MCP Inspector:

npm install -g @modelcontextprotocol/inspector
mcp-inspector  # Start inspector at http://localhost:5173

Architecture

Single-File Design

The entire server is implemented in src/index.ts (~1800 lines). Key sections in order:

  1. Logging System (lines ~56-424) - McpLogger class with structured JSON logging to stderr
  2. Zod Validation Schemas (lines ~454-627) - Input validation for all 5 tools
  3. Version Differences (lines ~747-826) - STRAPI_VERSION_DIFFERENCES constant for v4/v5
  4. Configuration (lines ~828-851) - Loads from ~/.mcp/strapi-mcp-server.config.json
  5. Server Setup (lines ~853-1024) - MCP server with capabilities including security policy
  6. Helper Functions (lines ~1026-1167) - getServerConfig, makeStrapiRequest, image processing
  7. Tool Handlers (lines ~1241-1675) - ListToolsRequestSchema and CallToolRequestSchema handlers
  8. REST/Upload Functions (lines ~1678-1812) - makeRestRequest, handleStrapiError

Validation Flow

All tool inputs are validated through Zod schemas before execution:

Tool Call → validateToolInput() → Zod Schema → Validated Args → Handler
                    ↓ (on error)
          McpError with detailed validation errors

Key schemas: ListServersSchema, GetContentTypesSchema, GetComponentsSchema, RestSchema, UploadMediaSchema

Security Model

Write operations (POST, PUT, DELETE, media upload) require userAuthorized: true parameter. This is enforced at two levels:

  1. Zod schema refinement (validation fails if missing)
  2. Runtime check in makeRestRequest() and uploadMedia()

Strapi Version Handling

Supports both v4 and v5 with automatic detection from config version string formats:

  • "5.*", "4.*" - Wildcard
  • "v4", "v5" - Simple prefix
  • "4.1.5", "5.0.0" - Specific version

Tools Provided

Tool Description
strapi_list_servers List configured servers with version info
strapi_get_content_types Schema introspection for all content types
strapi_get_components Component schemas with pagination
strapi_rest REST API operations (GET/POST/PUT/DELETE)
strapi_upload_media Media upload with format conversion via Sharp

Code Style

  • TypeScript strict mode with ES2022 target, Node16 module resolution
  • ES modules (import/export)
  • 2-space indentation, semicolons required
  • camelCase for variables/functions, PascalCase for types/interfaces
  • Logs go to stderr (not stdout) to avoid interfering with MCP protocol

Key Dependencies

  • @modelcontextprotocol/sdk - MCP server implementation
  • zod - Runtime input validation
  • sharp - Image processing and format conversion
  • qs - Query string serialization for REST params
  • form-data + node-fetch - Media upload handling

Version Differences (v4 vs v5)

Aspect v4 v5
ID Field id (numeric) documentId (string)
Response Structure Wrapped in data Flat/direct access
Attributes Nested under attributes Direct at root level

Commit Guidelines

  • Git commits in English without any mention of Claude, Anthropic, or promotional content
⚡