@williamzujkowski/live-coding-music-mcp 1.0.0

package/dist/utils/Logger.js

@@ -0,0 +1,19 @@
+export class Logger {
+    getTimestamp() {
+        return new Date().toISOString();
+    }
+    info(message, data) {
+        console.error(`[${this.getTimestamp()}] INFO: ${message}`, data ? JSON.stringify(data) : '');
+    }
+    error(message, error) {
+        console.error(`[${this.getTimestamp()}] ERROR: ${message}`, error?.message || error);
+    }
+    warn(message, data) {
+        console.error(`[${this.getTimestamp()}] WARN: ${message}`, data ? JSON.stringify(data) : '');
+    }
+    debug(message, data) {
+        if (process.env.DEBUG) {
+            console.error(`[${this.getTimestamp()}] DEBUG: ${message}`, data ? JSON.stringify(data) : '');
+        }
+    }
+}

package/dist/utils/PatternValidator.js

@@ -0,0 +1,241 @@
+/**
+ * PatternValidator - Validates Strudel patterns before execution
+ * Provides syntax checking and error recovery for generated patterns
+ */
+export class PatternValidator {
+    /**
+     * Validates a Strudel pattern for syntax errors
+     * @param pattern - The pattern code to validate
+     * @returns ValidationResult with errors and suggestions
+     */
+    validate(pattern) {
+        const errors = [];
+        const warnings = [];
+        const suggestions = [];
+        // Check for empty pattern
+        if (!pattern || pattern.trim().length === 0) {
+            errors.push('Pattern is empty');
+            suggestions.push('Add a simple pattern like: s("bd*4")');
+            return { valid: false, errors, warnings, suggestions };
+        }
+        // Check for balanced parentheses
+        const parenCheck = this.checkBalancedParentheses(pattern);
+        if (!parenCheck.valid) {
+            errors.push(`Unbalanced parentheses: ${parenCheck.message}`);
+            suggestions.push('Check that all ( ) [ ] { } are properly matched');
+        }
+        // Check for balanced quotes
+        const quoteCheck = this.checkBalancedQuotes(pattern);
+        if (!quoteCheck.valid) {
+            errors.push(`Unbalanced quotes: ${quoteCheck.message}`);
+            suggestions.push('Ensure all strings are properly quoted');
+        }
+        // Check for common Strudel syntax patterns
+        const syntaxCheck = this.checkStrudelSyntax(pattern);
+        warnings.push(...syntaxCheck.warnings);
+        suggestions.push(...syntaxCheck.suggestions);
+        // Check for dangerous operations
+        const safetyCheck = this.checkSafety(pattern);
+        if (!safetyCheck.safe) {
+            errors.push(...safetyCheck.errors);
+        }
+        warnings.push(...safetyCheck.warnings);
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            suggestions
+        };
+    }
+    /**
+     * Checks if parentheses, brackets, and braces are balanced
+     */
+    checkBalancedParentheses(pattern) {
+        const stack = [];
+        const pairs = { '(': ')', '[': ']', '{': '}' };
+        const opening = Object.keys(pairs);
+        const closing = Object.values(pairs);
+        for (let i = 0; i < pattern.length; i++) {
+            const char = pattern[i];
+            if (opening.includes(char)) {
+                stack.push(char);
+            }
+            else if (closing.includes(char)) {
+                if (stack.length === 0) {
+                    return { valid: false, message: `Unexpected closing '${char}' at position ${i}` };
+                }
+                const last = stack.pop();
+                if (pairs[last] !== char) {
+                    return { valid: false, message: `Mismatched '${last}' and '${char}' at position ${i}` };
+                }
+            }
+        }
+        if (stack.length > 0) {
+            return { valid: false, message: `Unclosed '${stack[stack.length - 1]}'` };
+        }
+        return { valid: true, message: '' };
+    }
+    /**
+     * Checks if quotes are balanced
+     */
+    checkBalancedQuotes(pattern) {
+        let inSingleQuote = false;
+        let inDoubleQuote = false;
+        let inBacktick = false;
+        for (let i = 0; i < pattern.length; i++) {
+            const char = pattern[i];
+            const prevChar = i > 0 ? pattern[i - 1] : '';
+            // Skip escaped quotes
+            if (prevChar === '\\') {
+                continue;
+            }
+            if (char === "'" && !inDoubleQuote && !inBacktick) {
+                inSingleQuote = !inSingleQuote;
+            }
+            else if (char === '"' && !inSingleQuote && !inBacktick) {
+                inDoubleQuote = !inDoubleQuote;
+            }
+            else if (char === '`' && !inSingleQuote && !inDoubleQuote) {
+                inBacktick = !inBacktick;
+            }
+        }
+        if (inSingleQuote) {
+            return { valid: false, message: 'Unclosed single quote' };
+        }
+        if (inDoubleQuote) {
+            return { valid: false, message: 'Unclosed double quote' };
+        }
+        if (inBacktick) {
+            return { valid: false, message: 'Unclosed backtick' };
+        }
+        return { valid: true, message: '' };
+    }
+    /**
+     * Checks for common Strudel syntax patterns and potential issues
+     */
+    checkStrudelSyntax(pattern) {
+        const warnings = [];
+        const suggestions = [];
+        // Check for common Strudel functions
+        const hasSound = /s\(/.test(pattern);
+        const hasNote = /note\(/.test(pattern);
+        const hasStack = /stack\(/.test(pattern);
+        if (!hasSound && !hasNote && !hasStack) {
+            warnings.push('Pattern may not produce sound - no s(), note(), or stack() found');
+            suggestions.push('Try adding s("bd*4") for a basic kick drum pattern');
+        }
+        // Check for common mistakes
+        if (/s\([^"']/.test(pattern)) {
+            warnings.push('Sound patterns should be in quotes: s("bd") not s(bd)');
+        }
+        // Check for undefined variables
+        const functionCalls = pattern.match(/\b([a-z_][a-z0-9_]*)\s*\(/gi);
+        if (functionCalls) {
+            const knownFunctions = [
+                's', 'note', 'stack', 'setcpm', 'sound', 'n', 'room', 'delay',
+                'reverb', 'fast', 'slow', 'rev', 'iter', 'jux', 'every', 'sometimes',
+                'rarely', 'often', 'gain', 'pan', 'cutoff', 'resonance', 'attack',
+                'release', 'sustain', 'decay', 'lpf', 'hpf', 'bpf', 'struct', 'euclid',
+                'euclidLegacy', 'choose', 'chooseWith', 'range', 'sine', 'saw', 'square',
+                'tri', 'rand', 'perlin', 'add', 'sub', 'mul', 'div', 'mod', 'pow',
+                'min', 'max', 'floor', 'ceil', 'round'
+            ];
+            functionCalls.forEach(call => {
+                const funcName = call.replace(/\s*\($/, '').toLowerCase();
+                if (!knownFunctions.includes(funcName)) {
+                    warnings.push(`Unknown function: ${funcName}`);
+                }
+            });
+        }
+        // Check for tempo setting
+        if (!pattern.includes('setcpm') && !pattern.includes('cpm')) {
+            suggestions.push('Consider adding setcpm(120) to set tempo');
+        }
+        return { warnings, suggestions };
+    }
+    /**
+     * Checks for potentially dangerous operations
+     */
+    checkSafety(pattern) {
+        const errors = [];
+        const warnings = [];
+        // Check for excessive gain that could damage speakers
+        const gainMatches = pattern.match(/\.gain\(([0-9.]+)\)/g);
+        if (gainMatches) {
+            gainMatches.forEach(match => {
+                const gainValue = parseFloat(match.match(/([0-9.]+)/)?.[0] || '0');
+                if (gainValue > 2) {
+                    warnings.push(`High gain value detected: ${gainValue} - may be too loud`);
+                }
+                if (gainValue > 5) {
+                    errors.push(`Dangerous gain value: ${gainValue} - reduced to 2.0 for safety`);
+                }
+            });
+        }
+        // Check for potentially infinite loops
+        if (/while\s*\(true\)/.test(pattern) || /for\s*\(.*;;.*\)/.test(pattern)) {
+            errors.push('Potential infinite loop detected');
+        }
+        // Check for eval or similar dangerous functions
+        if (/\beval\(/.test(pattern) || /Function\(/.test(pattern)) {
+            errors.push('Use of eval() or Function() is not allowed');
+        }
+        return {
+            safe: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Attempts to auto-fix common pattern errors
+     * @param pattern - The pattern to fix
+     * @returns Fixed pattern with applied corrections
+     */
+    autoFix(pattern) {
+        const fixes = [];
+        let fixed = pattern;
+        // Fix excessive gain values
+        fixed = fixed.replace(/\.gain\(([0-9.]+)\)/g, (match, value) => {
+            const gainValue = parseFloat(value);
+            if (gainValue > 2) {
+                fixes.push(`Reduced gain from ${gainValue} to 2.0`);
+                return '.gain(2.0)';
+            }
+            return match;
+        });
+        // Add missing quotes around sound patterns
+        fixed = fixed.replace(/s\(([a-z0-9*]+)\)/gi, (match, sound) => {
+            if (!sound.includes('"') && !sound.includes("'")) {
+                fixes.push(`Added quotes around sound: ${sound}`);
+                return `s("${sound}")`;
+            }
+            return match;
+        });
+        return { pattern: fixed, fixes };
+    }
+    /**
+     * Provides helpful suggestions based on pattern analysis
+     * @param pattern - The pattern to analyze
+     * @returns Array of suggestions for improvement
+     */
+    suggest(pattern) {
+        const suggestions = [];
+        // Suggest adding effects if pattern is plain
+        if (!pattern.includes('room') && !pattern.includes('delay') && !pattern.includes('reverb')) {
+            suggestions.push('Consider adding spatial effects: .room(0.5) or .delay(0.25)');
+        }
+        // Suggest adding variation
+        if (!pattern.includes('sometimes') && !pattern.includes('every')) {
+            suggestions.push('Add variation with .sometimes() or .every()');
+        }
+        // Suggest structure if pattern is very simple
+        if (pattern.length < 30 && pattern.includes('s(')) {
+            suggestions.push('Try stacking multiple patterns with stack()');
+        }
+        // Suggest tempo control
+        if (!pattern.includes('setcpm') && !pattern.includes('cpm')) {
+            suggestions.push('Set tempo with setcpm(120) at the beginning');
+        }
+        return suggestions;
+    }
+}

package/dist/utils/PerformanceMonitor.js

@@ -0,0 +1,128 @@
+export class PerformanceMonitor {
+    metrics = new Map();
+    startTimes = new Map();
+    getTime;
+    constructor(timeProvider) {
+        this.getTime = timeProvider || (() => performance.now());
+    }
+    startOperation(operationName) {
+        this.startTimes.set(operationName, this.getTime());
+    }
+    endOperation(operationName, success = true) {
+        const startTime = this.startTimes.get(operationName);
+        if (startTime === undefined)
+            return 0;
+        const duration = this.getTime() - startTime;
+        this.startTimes.delete(operationName);
+        const metric = this.metrics.get(operationName) || {
+            count: 0,
+            totalTime: 0,
+            minTime: Infinity,
+            maxTime: 0,
+            errors: 0
+        };
+        metric.count++;
+        metric.totalTime += duration;
+        metric.minTime = Math.min(metric.minTime, duration);
+        metric.maxTime = Math.max(metric.maxTime, duration);
+        if (!success)
+            metric.errors++;
+        this.metrics.set(operationName, metric);
+        return duration;
+    }
+    async measureAsync(operationName, operation) {
+        this.startOperation(operationName);
+        try {
+            const result = await operation();
+            this.endOperation(operationName, true);
+            return result;
+        }
+        catch (error) {
+            this.endOperation(operationName, false);
+            throw error;
+        }
+    }
+    getMetrics(operationName) {
+        if (operationName !== undefined) {
+            const metric = this.metrics.get(operationName);
+            if (!metric)
+                return null;
+            return {
+                operation: operationName,
+                calls: metric.count,
+                averageTime: metric.totalTime / metric.count,
+                minTime: metric.minTime,
+                maxTime: metric.maxTime,
+                totalTime: metric.totalTime,
+                errorRate: (metric.errors / metric.count) * 100
+            };
+        }
+        const allMetrics = [];
+        this.metrics.forEach((metric, name) => {
+            allMetrics.push({
+                operation: name,
+                calls: metric.count,
+                averageTime: metric.totalTime / metric.count,
+                minTime: metric.minTime,
+                maxTime: metric.maxTime,
+                totalTime: metric.totalTime,
+                errorRate: (metric.errors / metric.count) * 100
+            });
+        });
+        return allMetrics.sort((a, b) => b.totalTime - a.totalTime);
+    }
+    getReport() {
+        const metrics = this.getMetrics();
+        if (!metrics || metrics.length === 0) {
+            return 'No performance metrics collected';
+        }
+        let report = '\n=== PERFORMANCE REPORT ===\n\n';
+        report += 'Operation'.padEnd(30) + 'Calls'.padEnd(10) + 'Avg(ms)'.padEnd(12) + 'Min(ms)'.padEnd(12) + 'Max(ms)'.padEnd(12) + 'Errors\n';
+        report += '-'.repeat(86) + '\n';
+        metrics.forEach(m => {
+            report += m.operation.padEnd(30) +
+                m.calls.toString().padEnd(10) +
+                m.averageTime.toFixed(2).padEnd(12) +
+                m.minTime.toFixed(2).padEnd(12) +
+                m.maxTime.toFixed(2).padEnd(12) +
+                `${m.errorRate.toFixed(1)}%\n`;
+        });
+        const totalCalls = metrics.reduce((sum, m) => sum + m.calls, 0);
+        const totalTime = metrics.reduce((sum, m) => sum + m.totalTime, 0);
+        report += '\n';
+        report += `Total Operations: ${totalCalls}\n`;
+        report += `Total Time: ${totalTime.toFixed(2)}ms\n`;
+        report += `Average per Operation: ${(totalTime / totalCalls).toFixed(2)}ms\n`;
+        return report;
+    }
+    reset() {
+        this.metrics.clear();
+        this.startTimes.clear();
+    }
+    // Memory usage tracking
+    getMemoryUsage() {
+        if (typeof process !== 'undefined' && process.memoryUsage) {
+            const usage = process.memoryUsage();
+            return {
+                heapUsed: (usage.heapUsed / 1024 / 1024).toFixed(2) + ' MB',
+                heapTotal: (usage.heapTotal / 1024 / 1024).toFixed(2) + ' MB',
+                rss: (usage.rss / 1024 / 1024).toFixed(2) + ' MB',
+                external: (usage.external / 1024 / 1024).toFixed(2) + ' MB'
+            };
+        }
+        return null;
+    }
+    // Get top slowest operations
+    getBottlenecks(limit = 5) {
+        const metrics = this.getMetrics();
+        return metrics
+            .sort((a, b) => b.averageTime - a.averageTime)
+            .slice(0, limit)
+            .map(m => ({
+            operation: m.operation,
+            averageTime: m.averageTime.toFixed(2) + 'ms',
+            maxTime: m.maxTime.toFixed(2) + 'ms',
+            calls: m.calls
+        }));
+    }
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@williamzujkowski/live-coding-music-mcp",
+  "version": "1.0.0",
+  "description": "MCP server (unofficial, fan project) for AI-assisted live-coding music via strudel.cc. Lets Claude drive pattern generation, audio analysis, and MIDI export through the Strudel browser REPL.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "live-coding-music-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc && npx tsx scripts/generate-tool-docs.ts",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "jest --coverage",
+    "test:nocov": "jest",
+    "test:watch": "jest --watch",
+    "test:integration": "node tests/strudel-integration.js",
+    "test:browser": "HEADLESS=true jest --testPathPattern=browser",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "docker:build": "docker build -t live-coding-music-mcp .",
+    "docker:run": "docker-compose up",
+    "prepublishOnly": "npm run build && npm run test:nocov -- --testPathIgnorePatterns=browser",
+    "prepare": "npm run build",
+    "validate": "echo '{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}' | node dist/index.js",
+    "benchmark": "tsx src/__tests__/benchmarks/latency.benchmark.ts",
+    "benchmark:gate": "tsx src/__tests__/benchmarks/latency.benchmark.ts --gate",
+    "clean": "rm -rf dist coverage"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@strudel/core": "1.2.5",
+    "@strudel/mini": "1.2.5",
+    "@strudel/tonal": "1.2.5",
+    "@strudel/transpiler": "1.2.5",
+    "@tonejs/midi": "^2.0.28",
+    "google-auth-library": "^10.5.0",
+    "playwright": "^1.52.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^22",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.0",
+    "ts-jest": "^29.1.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/williamzujkowski/live-coding-music-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "strudel",
+    "tidalcycles",
+    "music",
+    "ai",
+    "claude",
+    "live-coding",
+    "algorithmic-composition",
+    "web-audio",
+    "music-generation"
+  ],
+  "author": "William Zujkowski <william.zujkowski@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/williamzujkowski/live-coding-music-mcp/issues"
+  },
+  "homepage": "https://github.com/williamzujkowski/live-coding-music-mcp#readme",
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=10.0.0"
+  }
+}