Strudel MCP Server

Instructions

Implementation Reference

• src/server/EnhancedMCPServerFixed.ts:286-290 (registration)

  MCP tool registration defining the 'detect_key' tool with name, description, and empty input schema (no parameters required).
  { name: 'detect_key', description: 'Key detection', inputSchema: { type: 'object', properties: {} } },
• src/server/EnhancedMCPServerFixed.ts:1001-1041 (handler)

  MCP server handler for 'detect_key' tool: checks initialization, calls controller.detectKey(), processes KeyAnalysis result into standardized output with confidence, alternatives, and error handling.
  case 'detect_key': if (!this.isInitialized) { return 'Browser not initialized. Run init first.'; } try { const keyAnalysis = await this.controller.detectKey(); if (!keyAnalysis || keyAnalysis.confidence < 0.1) { return { key: 'Unknown', scale: 'unknown', confidence: 0, message: 'No clear key detected. Ensure audio is playing and has tonal content.' }; } const result: any = { key: keyAnalysis.key, scale: keyAnalysis.scale, confidence: Math.round(keyAnalysis.confidence * 100) / 100, message: `Detected ${keyAnalysis.key} ${keyAnalysis.scale} with ${Math.round(keyAnalysis.confidence * 100)}% confidence` }; // Include alternatives if available and confidence is moderate if (keyAnalysis.alternatives && keyAnalysis.alternatives.length > 0) { result.alternatives = keyAnalysis.alternatives.map((alt: any) => ({ key: alt.key, scale: alt.scale, confidence: Math.round(alt.confidence * 100) / 100 })); } return result; } catch (error: any) { return { key: 'Unknown', scale: 'unknown', confidence: 0, error: error.message || 'Key detection failed' }; }
• src/StrudelController.ts:280-284 (helper)

  Delegation helper in StrudelController: forwards detectKey call to AudioAnalyzer instance with the browser page.
  async detectKey(): Promise<KeyAnalysis | null> { if (!this._page) throw new Error('Browser not initialized. Run init tool first.'); return await this.analyzer.detectKey(this._page); }
• src/AudioAnalyzer.ts:487-600 (handler)

  Core key detection handler: extracts chroma vector from audio analyzer data, correlates with scale profiles using cosine similarity and Krumhansl-Schmuckler algorithm, applies tonal biases, computes confidence and alternatives.
  async detectKey(page: Page): Promise<KeyAnalysis | null> { // Get analyzer object from browser const analyzer = await page.evaluate(() => { return (window as any).strudelAudioAnalyzer; }); if (!analyzer || !analyzer.isConnected) { throw new Error('Audio analyzer not connected'); } let chroma: number[]; // Check if this is a mock with pre-calculated chroma vector (for testing) if (typeof analyzer.analyze === 'function') { const analysis = analyzer.analyze(); if (analysis?.features?.chromaVector) { chroma = analysis.features.chromaVector; } else { // No mock data, extract from FFT if (!analyzer.dataArray) { throw new Error('Invalid audio data'); } const fftData = new Uint8Array(analyzer.dataArray); chroma = this.extractChroma(fftData); } } else { // No analyze function, extract from FFT if (!analyzer.dataArray) { throw new Error('Invalid audio data'); } const fftData = new Uint8Array(analyzer.dataArray); chroma = this.extractChroma(fftData); } // Check for sufficient energy const totalEnergy = chroma.reduce((sum, val) => sum + val, 0); if (totalEnergy < 0.1) { return { key: 'C', scale: 'major', confidence: 0.1 }; } // Correlate with all key/scale combinations const scores: Array<{ key: string; scale: string; score: number }> = []; for (const scale of Object.keys(this.SCALE_PROFILES)) { // Normalize profile to sum to 1 const rawProfile = this.SCALE_PROFILES[scale]; const profileSum = rawProfile.reduce((a, b) => a + b, 0); const profile = rawProfile.map(v => v / profileSum); for (let tonic = 0; tonic < 12; tonic++) { // Rotate chroma to align with profile // Put the tonic at position 0 to match the profile structure const rotatedChroma = new Array(12); for (let i = 0; i < 12; i++) { rotatedChroma[i] = chroma[(i + tonic) % 12]; } // Use cosine similarity for correlation const correlation = this.cosineSimilarity(rotatedChroma, profile); scores.push({ key: this.PITCH_CLASSES[tonic], scale, score: correlation }); } } // Find the top 3 loudest pitch classes - any could be the tonic const chromaWithIndices = chroma.map((v, i) => ({ value: v, index: i })); chromaWithIndices.sort((a, b) => b.value - a.value); const topPitches = chromaWithIndices.slice(0, 3).map(x => this.PITCH_CLASSES[x.index]); // Apply bias boosts to resolve ambiguous cases for (const s of scores) { // Boost keys that match one of the top 3 loudest pitches // (any of these could plausibly be the tonic) const pitchBoost = topPitches.indexOf(s.key); if (pitchBoost >= 0) { // Slightly favor 2nd pitch to handle dominant/mediant being louder than tonic const boosts = [1.075, 1.075, 1.075]; s.score *= boosts[pitchBoost]; } // Boost for common scales if (s.scale === 'major') { s.score *= 1.03; // 3% boost for major scales (most common) } else if (s.scale === 'dorian') { s.score *= 1.015; // 1.5% boost for dorian (common modal scale) } } // Sort by score (after applying biases) scores.sort((a, b) => b.score - a.score); // Calculate confidence const best = scores[0]; const secondBest = scores[1]; // Confidence based on score strength (cosine similarity 0-1) and separation // Increased separation weight to better differentiate close matches const strength = best.score; const separation = Math.min(1, Math.max(0, (best.score - secondBest.score) * 10)); const confidence = Math.min(1, strength * 0.75 + separation * 0.25); return { key: best.key, scale: best.scale as any, confidence, alternatives: scores.slice(1, 4).map(s => ({ key: s.key, scale: s.scale, confidence: Math.max(0, s.score) })) }; }