feat: Add MCP analysis profiles and structured output format

- Add 5 analysis profiles: quick, standard, detailed, fingerprint, mastering
- Implement structured response with categorized audio/content/quality/fingerprint info
- Add hierarchical insights categorized by severity (critical/warnings/info/suggestions)
- Enhance audio comparison with multi-dimensional similarity scoring
- Add progress tracking with completed/pending module status
- Update documentation and examples with new MCP features

Author: willibrandon

README.md

@@ -94,22 +94,39 @@ ferrous-waves serve
 
 The server exposes three tools:
 
-#### `analyze_audio` - Comprehensive audio analysis with filtering and pagination
+#### `analyze_audio` - Analyze audio files with configurable depth
 Parameters:
 - `file_path` (required): Path to audio file
+- `analysis_profile`: Choose analysis depth (default: "standard")
+  - `"quick"`: Basic metrics only (fastest)
+  - `"standard"`: Core audio features
+  - `"detailed"`: All analysis modules
+  - `"fingerprint"`: Focus on similarity detection
+  - `"mastering"`: Focus on loudness and quality metrics
 - `return_format`: "summary" (default), "full", or "visual_only"
 - `include_visuals`: Include base64-encoded images (default: false, WARNING: very large)
 - `include_spectral`: Include spectral data arrays (default: false)
 - `include_temporal`: Include temporal data arrays (default: false)
 - `max_data_points`: Limit array sizes for pagination (default: 1000)
 - `cursor`: Continue from previous response's next_cursor
 
-#### `compare_audio` - Compare two audio files with fingerprint similarity
+Response format includes:
+- Audio properties (format, duration, sample rate, channels)
+- Content type and confidence scores
+- Quality metrics (loudness LUFS, true peak, dynamic range)
+- Issues categorized by severity (critical, warnings, info)
+- Fingerprint data for similarity matching
+
+#### `compare_audio` - Compare two audio files
 Parameters:
 - `file_a`, `file_b` (required): Paths to audio files
 - `metrics`: Optional comparison metrics to calculate
 
-Returns fingerprint similarity score (0.0-1.0) and match type (Identical, Similar, Different, etc.)
+Returns:
+- Similarity scores: overall, fingerprint, spectral, perceptual, structural (0.0-1.0 scale)
+- Differences: loudness delta, tempo delta, quality delta, key change
+- Match type: Identical, Very Similar, Similar, Different
+- Use case suggestions: "Same recording", "Different master", "Cover version", etc.
 
 #### `get_job_status` - Check analysis job status
 Parameters:

examples/README.md

@@ -53,7 +53,12 @@ The `envelope_visualization` example creates a PNG image showing waveform with p
 
 ## MCP Server
 
-The `mcp_client.rs` example shows the JSON format for MCP tool calls. To use the actual MCP server:
+The `mcp_client.rs` example shows the JSON format for MCP tool calls, including:
+- Different analysis profiles (quick, standard, detailed, fingerprint, mastering)
+- Pagination with cursors
+- Comparison with similarity scoring
+
+To use the actual MCP server:
 
 ```bash
 # Start the MCP server

examples/mcp_client.rs

@@ -7,33 +7,47 @@ fn main() {
     println!("Example MCP Tool Calls:");
     println!();
 
-    // Example 1: Analyze with default settings (returns compact summary)
-    let analyze_summary = json!({
+    // Example 1: Analyze with different profiles
+    let analyze_quick = json!({
         "tool": "analyze_audio",
         "arguments": {
-            "file_path": "/path/to/audio.wav"
+            "file_path": "/path/to/audio.wav",
+            "analysis_profile": "quick"  // Fast analysis
+        }
+    });
+    println!("1. Analyze Audio (Quick Profile):");
+    println!("{}", serde_json::to_string_pretty(&analyze_quick).unwrap());
+    println!();
+
+    // Example 1b: Mastering profile for quality focus
+    let analyze_mastering = json!({
+        "tool": "analyze_audio",
+        "arguments": {
+            "file_path": "/path/to/audio.wav",
+            "analysis_profile": "mastering"  // Focus on loudness and quality
         }
     });
-    println!("1. Analyze Audio (Summary - Default):");
+    println!("1b. Analyze Audio (Mastering Profile):");
     println!(
         "{}",
-        serde_json::to_string_pretty(&analyze_summary).unwrap()
+        serde_json::to_string_pretty(&analyze_mastering).unwrap()
     );
     println!();
 
-    // Example 2: Analyze with spectral data and pagination
+    // Example 2: Analyze with detailed profile for complete analysis
     let analyze_detailed = json!({
         "tool": "analyze_audio",
         "arguments": {
             "file_path": "/path/to/audio.wav",
+            "analysis_profile": "detailed",  // All modules
             "return_format": "full",
             "include_spectral": true,
             "include_temporal": true,
             "max_data_points": 100,
             "cursor": null
         }
     });
-    println!("2. Analyze Audio (Full with Pagination):");
+    println!("2. Analyze Audio (Detailed Profile with Full Data):");
     println!(
         "{}",
         serde_json::to_string_pretty(&analyze_detailed).unwrap()