/**
* Clean-Cut-MCP Project Deep Dive Skill
*
* This skill performs a comprehensive analysis of the Clean-Cut-MCP project structure,
* similar to professional project documentation. It maps the entire codebase including:
* - Complete directory structure with file purposes
* - Component architecture and relationships
* - MCP server tools and validation system
* - Docker architecture and data flow
* - Development workflow and best practices
*
* Usage: /project-deep-dive
*/
const fs = require('fs');
const path = require('path');
class ProjectDeepDive {
constructor() {
this.projectRoot = process.cwd();
this.analysis = {
structure: {},
components: {},
mcpTools: {},
validation: {},
docker: {},
workflow: {}
};
}
async execute() {
console.log('š Starting Clean-Cut-MCP Project Deep Dive Analysis...\n');
await this.analyzeProjectStructure();
await this.analyzeComponents();
await this.analyzeMcpTools();
await this.analyzeValidation();
await this.analyzeDocker();
await this.analyzeWorkflow();
this.generateReport();
}
async analyzeProjectStructure() {
console.log('š Analyzing Project Structure...');
const structure = {
'MCP Server Core': {
path: 'mcp-server/',
purpose: 'Main MCP server with validation and code generation',
files: {
'clean-stdio-server.ts': 'Production MCP server (lines 1034-1120 validation)',
'http-mcp-server.ts': 'Development HTTP server',
'animation-validator.ts': 'Animation validation logic',
'base-animation-rules.ts': 'Professional standards enforcement',
'preference-learner.ts': 'User correction learning system',
'rule-enforcer.ts': 'Combined base + learned rules',
'root-sync.ts': 'Auto-sync Root.tsx with animations',
'template-registry.ts': 'Animation template management',
'preference-applier.ts': 'Apply learned preferences'
}
},
'Animation Workspace': {
path: 'clean-cut-workspace/',
purpose: 'Animation development environment',
subdirs: {
'src/assets/animations/': 'Individual animation components (20+ files)',
'src/components/': 'Shared React components (NoOverlapScene, etc.)',
'src/utils/': 'Animation utilities (kinetic-text, camera-controller)',
'src/patterns/': 'Design patterns and templates',
'src/validated-params/': 'Pre-validated parameters',
'src/Root.tsx': 'Auto-generated composition registry'
}
},
'Docker Architecture': {
path: './',
purpose: 'Container configuration and deployment',
files: {
'Dockerfile': 'Multi-stage build (builder + runtime)',
'docker-compose.yml': 'Main service configuration',
'start.js': 'Container entry point and directory creation',
'auto-update-root.js': 'Root.tsx auto-sync helper',
'cleanup-service.js': 'File cleanup utilities'
}
},
'Documentation': {
path: 'claude-dev-guidelines/',
purpose: 'Project standards and configuration',
files: {
'PROJECT_CONFIG.md': 'Master configuration source',
'PRE-ANIMATION-CHECKLIST.md': 'Mandatory validation steps',
'SAFE_ANIMATION_CREATION_PROTOCOL.md': 'Creation workflow',
'ADVANCED/': 'Technical documentation and standards'
}
}
};
this.analysis.structure = structure;
console.log('ā Project structure analyzed\n');
}
async analyzeComponents() {
console.log('š§© Analyzing Component Architecture...');
const components = {
hierarchy: {
'RemotionRoot': {
purpose: 'Auto-generated composition registry',
children: {
'Main Composition': {
purpose: 'Container for all animations',
children: {
'Animation Components': {
count: '20+ individual animations',
examples: ['AllGasNoBrakesAnimation', 'FloatingOrbs', 'GitHubProfileShowcaseEnhanced'],
location: 'clean-cut-workspace/src/assets/animations/'
},
'Shared Components': {
purpose: 'Reusable animation infrastructure',
components: {
'NoOverlapScene': 'Prevents element overlaps in multi-scene animations',
'MandatoryTransition': 'Ensures proper scene transitions',
'EnforcedScene': 'Validates scene boundaries'
},
location: 'clean-cut-workspace/src/components/'
}
}
}
}
}
},
utilities: {
'kinetic-text.ts': 'Advanced text animation with professional easing',
'camera-controller.ts': 'Camera movement and tracking systems',
'scale-isolation.ts': 'Scale validation and isolation',
'crop-detector.ts': 'Boundary detection and validation',
'particle-system.tsx': 'Particle effects management',
'professional-easing.ts': 'Research-validated motion curves'
},
standards: {
structure: 'export const ComponentName: React.FC<Schema> = (props) => { ... }',
validation: 'AST-based validation with auto-correction',
configuration: 'Reads from PROJECT_CONFIG.md (no hardcoded values)',
performance: 'Hot reload in Remotion Studio'
}
};
this.analysis.components = components;
console.log('ā Component architecture analyzed\n');
}
async analyzeMcpTools() {
console.log('š ļø Analyzing MCP Tools...');
const tools = {
total: 18,
categories: {
'Animation Creation': {
'create_animation': {
purpose: 'Main tool with comprehensive validation',
features: ['Base rules enforcement', 'Learned rules application', 'Auto-correction'],
location: 'clean-stdio-server.ts:1034-1120'
},
'update_composition': 'Modify existing animations',
'manage_props': 'Component property management'
},
'Root Management': {
'auto_sync': 'Auto-sync Root.tsx with animation files',
'rebuild_compositions': 'Regenerate Root.tsx from scratch',
'cleanup_broken_imports': 'Remove orphaned imports'
},
'Asset Management': {
'upload_asset': 'Upload images/logos to public folder',
'list_assets': 'List available assets',
'delete_asset': 'Remove asset files'
},
'Learning System': {
'generate_with_learning': 'Apply learned preferences to animations',
'record_user_correction': 'Store user feedback for future improvements',
'view_learned_preferences': 'Show learned rules and patterns'
},
'Utilities': {
'get_studio_url': 'Get Remotion Studio URL',
'list_existing_components': 'List all animation components',
'get_project_guidelines': 'Read project documentation',
'format_code': 'Format code with Prettier',
'get_export_directory': 'Get export location info'
}
},
entryPoints: {
'STDIO Server': 'clean-stdio-server.ts (production for Claude Desktop)',
'HTTP Server': 'http-mcp-server.ts (development/testing)'
}
};
this.analysis.mcpTools = tools;
console.log('ā MCP tools analyzed\n');
}
async analyzeValidation() {
console.log('ā
Analyzing Validation System...');
const validation = {
location: 'clean-stdio-server.ts lines 1034-1120',
pipeline: [
'Input Code ā Base Rules (Blocking) ā Learned Rules (Warnings) ā Syntax Check ā Auto-Correction ā Final Output'
],
baseRules: {
purpose: 'Professional broadcast standards (always enforced)',
rules: {
'Typography': {
'Font Family': 'Must be specified (no browser defaults)',
'Font Size': 'Minimum 24px for 1920x1080 resolution',
'Serif Detection': 'Warns about serif fonts (excludes sans-serif)'
},
'Structure': {
'NoOverlapScene': 'Required for multi-scene animations',
'Export Pattern': 'Proper export syntax validation',
'Dynamic Imports': 'Blocked for security'
},
'Layout': {
'Padding': 'Minimum 40px (no cramped layouts)',
'Element Size': 'Must be visible on 1920x1080'
},
'Motion': {
'Motion Blur': 'Required for fast movements',
'Duration': 'No arbitrary values'
}
}
},
learnedRules: {
purpose: 'User corrections and preferences',
storage: 'mcp-server/preferences/user-preferences.json',
examples: {
'Scale Limits': 'User prefers max scale 1.2 for logos',
'Color Preferences': 'User corrections for brand colors',
'Timing Adjustments': 'User preferred animation durations'
}
},
enforcement: {
blocking: 'Typography, Structure, Security violations',
warnings: 'Motion, Layout, Performance suggestions',
autoFix: 'Common issues automatically corrected'
}
};
this.analysis.validation = validation;
console.log('ā Validation system analyzed\n');
}
async analyzeDocker() {
console.log('š³ Analyzing Docker Architecture...');
const docker = {
build: {
type: 'Multi-stage (builder + runtime)',
stages: {
'Builder': 'Install dependencies, build TypeScript',
'Runtime': 'Copy built files, set entrypoint'
}
},
configuration: {
file: 'docker-compose.yml',
services: {
'clean-cut-mcp': {
ports: ['6970:6970 (Remotion Studio)', '6971:6971 (Future HTTP MCP)'],
volumes: [
'./clean-cut-workspace:/workspace (Animation source)',
'./clean-cut-exports:/workspace/out (Rendered videos)',
'clean-cut-node-modules:/workspace/node_modules (Avoid conflicts)'
],
environment: {
'DOCKER_CONTAINER': 'Path resolution signal',
'REMOTION_STUDIO_PORT': 'Studio access port',
'CHOKIDAR_USEPOLLING': 'File watching in Docker'
}
}
}
},
bindMounts: {
critical: 'Container must create directories at startup',
issue: 'Docker bind mounts dont sync directories created after container start',
solution: 'start.js creates all subdirectories before services start'
},
entrypoint: {
file: 'start.js',
responsibilities: [
'Create required directories',
'Set up environment',
'Start Remotion Studio',
'Start MCP server'
]
}
};
this.analysis.docker = docker;
console.log('ā Docker architecture analyzed\n');
}
async analyzeWorkflow() {
console.log('š Analyzing Development Workflow...');
const workflow = {
development: {
localSetup: [
'docker-compose build',
'docker-compose up -d',
'Access Remotion Studio: http://localhost:6970'
],
codeChanges: {
'MCP Server': [
'cd mcp-server && npm run build',
'docker cp dist/. clean-cut-mcp:/app/mcp-server/dist/',
'Restart Claude Desktop'
],
'Docker Changes': [
'docker-compose down',
'docker-compose build --no-cache',
'docker-compose up -d'
]
}
},
dataFlow: [
'Claude Desktop ā MCP Server ā Validation ā Code Generation ā File Creation ā Root.tsx Sync ā Studio Hot Reload'
],
testing: {
'MCP Server': 'npm run dev (HTTP mode)',
'Validation': 'node test-validation.js',
'Root Sync': 'docker exec clean-cut-mcp node -e "require(...).syncRootTsx()"',
'Studio': 'http://localhost:6970'
},
deployment: {
quickDeploy: 'Code-only changes (docker cp)',
fullRebuild: 'Dockerfile/dependency changes',
validation: 'Requires rebuild + deploy + Claude restart'
},
criticalGotchas: [
'Path resolution: Use process.env.DOCKER_CONTAINER checks',
'Directory creation: Container must create dirs at startup',
'Validation: Only works with rebuilt container',
'Root.tsx: Auto-syncs after each animation creation'
]
};
this.analysis.workflow = workflow;
console.log('ā Development workflow analyzed\n');
}
generateReport() {
console.log('š Clean-Cut-MCP Project Deep Dive Report');
console.log('=' .repeat(60));
console.log('\nšļø PROJECT OVERVIEW');
console.log('Clean-Cut-MCP is an AI-powered video generation system that runs as an MCP server in Docker.');
console.log('Users create professional Remotion animations using natural language through Claude Desktop.');
console.log('\nš DIRECTORY STRUCTURE');
console.log('ā¢ MCP Server Core (mcp-server/): Main server with validation and code generation');
console.log('ā¢ Animation Workspace (clean-cut-workspace/): 20+ animation components and utilities');
console.log('ā¢ Docker Architecture: Multi-stage containers with bind mounts');
console.log('ā¢ Documentation (claude-dev-guidelines/): Project standards and configuration');
console.log('\nš§© COMPONENT ARCHITECTURE');
console.log(`ā¢ ${Object.keys(this.analysis.components.hierarchy.RemotionRoot.children).length} main component categories`);
console.log(`ā¢ 20+ individual animation components`);
console.log('ā¢ 3 shared components (NoOverlapScene, MandatoryTransition, EnforcedScene)');
console.log('ā¢ 6 utility modules for animation support');
console.log('\nš ļø MCP TOOLS');
console.log(`ā¢ ${this.analysis.mcpTools.total} total tools across ${Object.keys(this.analysis.mcpTools.categories).length} categories`);
console.log('ā¢ 2 entry points (STDIO for production, HTTP for development)');
console.log('ā¢ Comprehensive validation system (lines 1034-1120)');
console.log('\nā
VALIDATION SYSTEM');
console.log('ā¢ Base Rules: Professional standards (always enforced)');
console.log('ā¢ Learned Rules: User corrections and preferences');
console.log('ā¢ Auto-correction: Common issues fixed automatically');
console.log('ā¢ 4 violation levels (Blocking, Warning, Info, Success)');
console.log('\nš³ DOCKER ARCHITECTURE');
console.log('ā¢ Multi-stage build (builder + runtime)');
console.log('ā¢ Critical bind mounts for workspace and exports');
console.log('ā¢ Environment-aware path resolution');
console.log('ā¢ Auto-directory creation in start.js');
console.log('\nš DEVELOPMENT WORKFLOW');
console.log('ā¢ Hot reload in Remotion Studio');
console.log('ā¢ Quick deploy for code changes');
console.log('ā¢ Full rebuild for Docker changes');
console.log('ā¢ Comprehensive testing strategy');
console.log('\nšÆ KEY FEATURES');
console.log('ā¢ Professional broadcast quality standards');
console.log('ā¢ User preference learning system');
console.log('ā¢ Template-based animation creation');
console.log('ā¢ AST-based validation and auto-correction');
console.log('ā¢ Claude Desktop integration via MCP');
console.log('\nš DOCUMENTATION');
console.log('Detailed mapping created in: docs/mapping/');
console.log('ā¢ PROJECT_STRUCTURE.md - Complete project overview');
console.log('ā¢ COMPONENT_ARCHITECTURE.md - Component relationships');
console.log('ā¢ MCP_SERVER_ARCHITECTURE.md - Server architecture details');
console.log('ā¢ VALIDATION_SYSTEM.md - Validation rules and enforcement');
console.log('ā¢ DEVELOPMENT_WORKFLOW.md - Development and deployment guide');
console.log('\n' + '='.repeat(60));
console.log('ā
Deep dive analysis complete!');
console.log('Project demonstrates sophisticated AI-powered video generation with');
console.log('professional quality standards and comprehensive validation systems.');
}
}
// Skill execution
async function runProjectDeepDive() {
const deepDive = new ProjectDeepDive();
await deepDive.execute();
}
// Main execution for direct testing
if (require.main === module) {
runProjectDeepDive().catch(console.error);
}
// Export for Claude Code
module.exports = { runProjectDeepDive, ProjectDeepDive };
