system-designer-mcp: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

This is a Model Context Protocol (MCP) server that provides AI agents with tools to create, validate, and export UML system models. The project uses a tool-based approach that empowers LLMs rather than trying to replace their natural language understanding capabilities.

Essential Commands

Development

# Start development server with watch mode
bun run dev

# Run tests
bun test
bun test --watch

# Build for production
bun run build
bun start

# Code quality
bun run lint          # Check for linting errors
bun run lint:fix      # Fix linting errors
bun run format        # Format code with Prettier
bun run format:check  # Check formatting without changes

Testing

# Run all tests
bun test

# Run in watch mode for development
bun test --watch

CLI Usage

# Test System Designer integration
bun run src/cli.ts test-integration

# Export a test model
bun run src/cli.ts export-model MyModel "Test model description"

# Show configuration
bun run src/cli.ts config

Architecture

Modular Structure (Post-Refactoring)

The codebase follows SOLID principles with clear separation of concerns:

• src/types.ts - TypeScript type definitions for MSON models and System Runtime bundles
• src/schemas.ts - Zod validation schemas for all data structures with flexible input handling
• src/tools.ts - MCP tool registration using modern SDK patterns
• src/index.ts - Main MCP server class with tool handler methods and ID mapping logic
• src/cli.ts - Command-line interface for testing and integration
• src/worker.ts - Cloudflare Workers implementation with modern JSON-RPC transport
• src/integration/system-designer.ts - System Designer app integration
• src/transformers/system-runtime.ts - MSON to System Runtime transformation logic
• src/validators/system-runtime.ts - System Runtime bundle validation