@ray0404/zig-audio-mcp 0.1.4 → 0.2.1

package/src/index.ts

@@ -2,9 +2,107 @@
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
+// Custom error types for structured error handling
+class McpResourceError extends Error {
+  constructor(uri: string) {
+    super(`Resource not found: ${uri}`);
+    this.name = "McpResourceError";
+  }
+}
+
+class McpToolError extends Error {
+  constructor(toolName: string, message: string) {
+    super(`Tool '${toolName}': ${message}`);
+    this.name = "McpToolError";
+  }
+}
+
+class McpValidationError extends Error {
+  constructor(message: string) {
+    super(`Validation error: ${message}`);
+    this.name = "McpValidationError";
+  }
+}
+
+// Structured logging utility
+const log = {
+  info: (message: string, data?: unknown) => {
+    console.error(`[INFO] ${message}`, data ? JSON.stringify(data) : "");
+  },
+  warn: (message: string, data?: unknown) => {
+    console.error(`[WARN] ${message}`, data ? JSON.stringify(data) : "");
+  },
+  error: (message: string, error?: unknown) => {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    console.error(`[ERROR] ${message}: ${errorMsg}`);
+  },
+  debug: (message: string, data?: unknown) => {
+    console.error(`[DEBUG] ${message}`, data ? JSON.stringify(data) : "");
+  }
+};
+
+// MCP Prompts data
+const PROMPTS = {
+  "library-selection": {
+    name: "library-selection",
+    description: "Help select the right audio library for your Zig project",
+    arguments: [
+      { name: "project_type", description: "synthesizer, audio-player, dsp-effects, file-io, sdr-radio, game-audio, embedded", required: true },
+      { name: "requirements", description: "optional: low-latency, no-allocations, cross-platform, simple-api", required: false }
+    ]
+  },
+  "synth-basics": {
+    name: "synth-basics",
+    description: "Step-by-step guide to building a basic synthesizer in Zig",
+    arguments: [
+      { name: "output_type", description: "wav-file, playback, both", required: false }
+    ]
+  },
+  "filter-design": {
+    name: "filter-design",
+    description: "Guide to designing audio filters in Zig",
+    arguments: [
+      { name: "filter_type", description: "lowpass, highpass, bandpass, notch, peaking", required: true },
+      { name: "sample_rate", description: "44100, 48000, 96000", required: false }
+    ]
+  },
+  "debugging-audio": {
+    name: "debugging-audio",
+    description: "Troubleshoot common audio programming issues",
+    arguments: [
+      { name: "issue", description: "glitches, latency, no-sound, crash, poor-quality", required: true }
+    ]
+  }
+};
+
+function generatePromptContent(promptName: string, args: Record<string, unknown>): string {
+  switch (promptName) {
+    case "library-selection": {
+      const projectType = args.project_type as string || "synthesizer";
+      const requirements = args.requirements as string || "";
+      return `Help select the best Zig audio library for a ${projectType} project${requirements ? ` with requirements: ${requirements}` : ""}.`;
+    }
+    case "synth-basics": {
+      const outputType = args.output_type as string || "playback";
+      return `Provide a step-by-step guide to building a basic synthesizer in Zig that outputs to ${outputType}. Include oscillator setup, envelope, and audio output.`;
+    }
+    case "filter-design": {
+      const filterType = args.filter_type as string || "lowpass";
+      const sampleRate = args.sample_rate as string || "44100";
+      return `Explain how to design and implement a ${filterType} filter in Zig at ${sampleRate}Hz sample rate. Include coefficient calculation and implementation code.`;
+    }
+    case "debugging-audio": {
+      const issue = args.issue as string || "glitches";
+      return `Help debug a ${issue} issue in Zig audio programming. What are common causes and solutions?`;
+    }
+    default:
+      return "Unknown prompt request";
+  }
+}
+
 // Library information database
 const ZIG_AUDIO_LIBRARIES = {
   zang: {
@@ -84,6 +182,45 @@ const ZIG_AUDIO_LIBRARIES = {
     examples: ["Entity-component audio", "High-performance mixing", "Modular processing"],
     api_docs: "https://github.com/chr15m/dalek",
     use_cases: ["Game engines", "High-performance audio", "Large-scale audio processing"]
+  },
+  "zsynth": {
+    name: "zsynth",
+    description: "Simple FM synthesis library for Zig.",
+    repo: "https://github.com/zsynth/zsynth",
+    license: "MIT",
+    features: ["fm-synthesis", "operators", "modulation"],
+    categories: ["synthesis", "effects"],
+    installation: "Add to build.zig.zon: .url = \"git+https://github.com/zsynth/zsynth#master\"",
+    version: "Zig 0.11+",
+    examples: ["FM operators", "Modulation matrices"],
+    api_docs: "https://github.com/zsynth/zsynth",
+    use_cases: ["FM synthesis", "Electronic tones", "Sound design"]
+  },
+  "zig-synth": {
+    name: "zig-synth",
+    description: "Zig wrapper for sokol_audio for low-latency audio.",
+    repo: "https://github.com/zig-synth/zig-synth",
+    license: "MIT",
+    features: ["low-latency", "sokol", "playback"],
+    categories: ["playback", "wrapper"],
+    installation: "Add to build.zig.zon: .url = \"git+https://github.com/zig-synth/zig-synth#master\"",
+    version: "Zig 0.10+",
+    examples: ["Simple playback", "Streaming"],
+    api_docs: "https://github.com/zig-synth/zig-synth",
+    use_cases: ["Games", "Interactive audio", "Low-latency apps"]
+  },
+  noize: {
+    name: "noize",
+    description: "Simple audio synthesis library with a focus on ease of use.",
+    repo: "https://github.com/noize/noize",
+    license: "MIT",
+    features: ["synthesis", "generators", "noise"],
+    categories: ["synthesis", "dsp"],
+    installation: "Add to build.zig.zon: .url = \"git+https://github.com/noize/noize#master\"",
+    version: "Zig 0.11+",
+    examples: ["Noise generators", "Basic synthesis"],
+    api_docs: "https://github.com/noize/noize",
+    use_cases: ["Prototyping", "Learning audio", "Simple synthesis"]
   }
 };
 
@@ -133,14 +270,174 @@ const DSP_FILTERS = {
   }
 };
 
+// MCP Resources - Static reference data exposed as resources
+const RESOURCES = {
+  "zig-audio://libraries": {
+    uri: "zig-audio://libraries",
+    name: "Zig Audio Libraries",
+    description: "Complete database of Zig audio/DSP libraries with details, features, and use cases",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: ZIG_AUDIO_LIBRARIES
+  },
+  "zig-dsp://filters": {
+    uri: "zig-dsp://filters",
+    name: "DSP Filter Reference",
+    description: "Reference for all DSP filter types with formulas, use cases, and compatible Zig libraries",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: DSP_FILTERS
+  },
+  "zig-dsp://concepts": {
+    uri: "zig-dsp://concepts",
+    name: "Audio/DSP Concepts",
+    description: "Fundamental audio and DSP terminology including sample rate, bit depth, buffer size, Nyquist frequency, and aliasing",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: {
+      "sample-rate": {
+        description: "Number of samples captured per second (e.g., 44100 Hz, 48000 Hz)",
+        typicalValues: [44100, 48000, 96000],
+        impact: "Higher rates = more accurate audio but more CPU/memory"
+      },
+      "bit-depth": {
+        description: "Number of bits per sample for amplitude resolution",
+        typicalValues: [16, 24, 32],
+        impact: "Higher depth = more dynamic range, less quantization noise"
+      },
+      "buffer-size": {
+        description: "Number of samples processed per callback cycle",
+        typicalValues: [64, 128, 256, 512, 1024],
+        impact: "Smaller = lower latency, higher CPU; larger = more stable, more latency"
+      },
+      "nyquist-frequency": {
+        description: "Maximum representable frequency (sample_rate / 2)",
+        formula: "f_nyquist = sample_rate / 2"
+      },
+      "aliasing": {
+        description: "Distortion from sampling frequencies above Nyquist",
+        prevention: "Use anti-aliasing filters before downsampling"
+      }
+    }
+  },
+  "zig-audio://templates/code": {
+    uri: "zig-audio://templates/code",
+    name: "Code Templates",
+    description: "Starter code templates for common audio/DSP tasks in Zig",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: {
+      oscillator: "Starter code for oscillators using zang",
+      envelope: "ADSR envelope implementation using zang",
+      filter: "Biquad filter implementation using zang",
+      delay: "Delay effect using bonk",
+      mixer: "Simple audio mixer implementation",
+      player: "Audio playback using zaudio",
+      recorder: "Audio recording using zaudio",
+      "file-write": "Write WAV file using pcm",
+      "file-read": "Read WAV file using pcm"
+    }
+  },
+  "zig-audio://templates/project": {
+    uri: "zig-audio://templates/project",
+    name: "Project Templates",
+    description: "Complete project skeletons for different audio application types",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: {
+      synthesizer: "Full synthesizer project with zang",
+      "audio-player": "Audio playback project with zaudio",
+      "dsp-processor": "DSP effects processor with bonk",
+      "file-processor": "Audio file processor with pcm",
+      "game-audio": "Game audio system with zang + zaudio"
+    }
+  },
+  "zig-audio://resources": {
+    uri: "zig-audio://resources",
+    name: "Learning Resources",
+    description: "Curated tutorials, examples, articles, and references for Zig audio development",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: [
+      { type: "tutorial", title: "Zig Audio Ecosystem Overview", url: "https://github.com/topics/zig-audio", description: "Overview of audio libraries in Zig ecosystem" },
+      { type: "tutorial", title: "Getting Started with Zang", url: "https://github.com/dbandstra/zang", description: "Complete guide to zang synthesis library" },
+      { type: "tutorial", title: "Audio Programming in Zig", url: "https://ziglang.org/learn/samples/#audio", description: "Official Zig language audio programming samples" },
+      { type: "example", title: "Zang Examples Repository", url: "https://github.com/dbandstra/zang/tree/master/examples", description: "Complete examples for oscillators, effects, and synthesis" },
+      { type: "reference", title: "Zaudio API Documentation", url: "https://github.com/MasterQ32/zaudio", description: "Complete API reference for miniaudio wrapper" },
+      { type: "reference", title: "Digital Signal Processing Fundamentals", url: "https://www.dspguide.com/", description: "Comprehensive DSP theory and algorithms reference" },
+      { type: "article", title: "Building Real-time Audio Apps in Zig", url: "https://christine.website/blog/zig-dsp-01-2024", description: "In-depth tutorial on DSP effects and real-time processing" },
+      { type: "reference", title: "Audio EQ Cookbook", url: "https://www.w3.org/TR/audio-eq-cookbook/", description: "Standard biquad filter coefficient calculations" },
+      { type: "tutorial", title: "Cross-Platform Audio Development", url: "https://miniaud.io/docs/manual/index.html", description: "Miniaudio documentation (used by zaudio)" },
+      { type: "forum", title: "Zig Discord Audio Channel", url: "https://discord.gg/zig-lang", description: "Zig language Discord server audio programming discussions" },
+      { type: "forum", title: "Ziggit Audio Forum", url: "https://ziggit.dev", description: "Zig community forum with audio programming topics" }
+    ]
+  },
+  "zig-audio://troubleshooting": {
+    uri: "zig-audio://troubleshooting",
+    name: "Troubleshooting Guide",
+    description: "Common audio programming issues and their solutions",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: {
+      "audio-glitches": { issue: "Audio glitches, pops, or clicks", likely_causes: ["Buffer size too small", "CPU overload", "Memory allocations in audio callback"], solutions: ["Increase buffer size", "Reduce processing complexity", "Use no-allocation libraries"] },
+      "latency": { issue: "High audio latency", likely_causes: ["Large buffer size", "Excessive processing"], solutions: ["Reduce buffer size", "Use low-latency libraries"] },
+      "no-sound": { issue: "No sound output", likely_causes: ["Audio device not initialized", "Volume at zero"], solutions: ["Verify device initialization", "Check system volume"] },
+      "crash": { issue: "Application crashes", likely_causes: ["Null pointer in audio callback", "Memory corruption"], solutions: ["Initialize all objects before use", "Use defer cleanup"] },
+      "compilation-error": { issue: "Compilation errors", likely_causes: ["Zig version mismatch", "Missing dependencies"], solutions: ["Check library's Zig version", "Verify module imports"] },
+      "performance": { issue: "Poor performance or high CPU", likely_causes: ["Inefficient algorithms", "Excessive allocations"], solutions: ["Pre-compute coefficients", "Avoid allocations in callbacks"] }
+    }
+  },
+  "zig-audio://compatibility": {
+    uri: "zig-audio://compatibility",
+    name: "Library Compatibility Matrix",
+    description: "Zig version compatibility status for each audio library",
+    mimeType: "application/json",
+    version: "0.2.0",
+    lastUpdated: "2026-03-28",
+    data: {
+      "zang": { latest_version: "0.12+ compatible", status: "active", notes: "Actively maintained" },
+      "zaudio": { latest_version: "Zig 0.11+", status: "needs-update", notes: "May need updates for Zig 0.12+" },
+      "bonk": { latest_version: "Zig 0.10+", status: "needs-update", notes: "Check for newer releases" },
+      "pcm": { latest_version: "Zig 0.9+", status: "deprecated", notes: "Very outdated, consider alternatives" },
+      "zig-liquid-dsp": { latest_version: "Zig 0.11+", status: "active", notes: "Check for 0.12 support" },
+      "dalek": { latest_version: "Zig 0.10+", status: "experimental", notes: "API may change" }
+    }
+  }
+};
+
+// Resource Templates for parameterized access
+const RESOURCE_TEMPLATES = [
+  {
+    uriTemplate: "zig-audio://libraries/{name}",
+    name: "Library Details",
+    description: "Get detailed information about a specific Zig audio library by name",
+    mimeType: "application/json"
+  },
+  {
+    uriTemplate: "zig-dsp://filters/{type}",
+    name: "Filter Details",
+    description: "Get detailed information about a specific DSP filter type",
+    mimeType: "application/json"
+  }
+];
+
 // Tool input validation schemas
+const LIBRARY_ENUM = z.enum(["zang", "zaudio", "bonk", "pcm", "zig-liquid-dsp", "dalek", "zsynth", "zig-synth", "noize"]);
+
 const ListLibrariesInput = z.object({
   category: z.enum(["synthesis", "effects", "filters", "dsp", "playback", "recording", "file-io", "encoding", "sdr", "engine", "wrapper", "experimental", "all"]).optional(),
   feature: z.string().optional()
 });
 
 const GetLibraryInfoInput = z.object({
-  library: z.enum(["zang", "zaudio", "bonk", "pcm", "zig-liquid-dsp", "dalek"])
+  library: LIBRARY_ENUM
 });
 
 const ExplainFilterInput = z.object({
@@ -153,7 +450,7 @@ const GenerateCodeInput = z.object({
 });
 
 const ListResourcesInput = z.object({
-  resource_type: z.enum(["tutorial", "reference", "example", "article"]).optional()
+  resource_type: z.enum(["tutorial", "reference", "example", "article", "video", "forum", "github-issues"]).optional()
 });
 
 const RecommendLibraryInput = z.object({
@@ -172,7 +469,7 @@ const DesignFilterInput = z.object({
 });
 
 const VerifyCodeInput = z.object({
-  code: z.string().describe("Zig code to verify for basic syntax and imports"),
+  code: z.string().max(50000).describe("Zig code to verify for basic syntax and imports"),
   libraries: z.array(z.string()).optional().describe("Expected libraries that should be imported")
 });
 
@@ -181,6 +478,31 @@ const ProjectTemplateInput = z.object({
   features: z.array(z.string()).optional().describe("Additional features to include")
 });
 
+const CompareLibrariesInput = z.object({
+  libraries: z.array(LIBRARY_ENUM).min(2).max(6)
+});
+
+const TroubleshootInput = z.object({
+  issue_type: z.enum(["audio-glitches", "latency", "no-sound", "crash", "compilation-error", "performance"])
+});
+
+const DeprecationCheckInput = z.object({
+  library: LIBRARY_ENUM,
+  zig_version: z.string().regex(/^\d+\.\d+\.\d+$/).optional()
+});
+
+const CalculateDelayInput = z.object({
+  value: z.number().positive(),
+  from_unit: z.enum(["ms", "samples", "feet", "meters"]),
+  to_unit: z.enum(["ms", "samples", "feet", "meters"]),
+  sample_rate: z.number().default(44100)
+});
+
+const UsePromptInput = z.object({
+  prompt_name: z.enum(["library-selection", "synth-basics", "filter-design", "debugging-audio"]),
+  arguments: z.record(z.unknown()).optional()
+});
+
 // Tool handlers
 async function handleListLibraries(args: unknown) {
   const input = ListLibrariesInput.parse(args);
@@ -217,12 +539,17 @@ async function handleVerifyCode(args: unknown) {
     suggestions.push('Add: const std = @import("std");');
   }
 
-  // Check for common library imports
+  // Check for all library imports
   const libraryChecks = [
     { lib: "zang", pattern: /zang\./, import: 'const zang = @import("zang");' },
     { lib: "zaudio", pattern: /zaudio\./, import: 'const zaudio = @import("zaudio");' },
     { lib: "bonk", pattern: /bonk\./, import: 'const bonk = @import("bonk");' },
-    { lib: "pcm", pattern: /pcm\./, import: 'const pcm = @import("pcm");' }
+    { lib: "pcm", pattern: /pcm\./, import: 'const pcm = @import("pcm");' },
+    { lib: "zig-liquid-dsp", pattern: /liquid\./, import: 'const liquid = @import("zig-liquid-dsp");' },
+    { lib: "dalek", pattern: /dalek\./, import: 'const dalek = @import("dalek");' },
+    { lib: "zsynth", pattern: /zsynth\./, import: 'const zsynth = @import("zsynth");' },
+    { lib: "sokol_audio", pattern: /sokol\./, import: 'const sokol = @import("sokol_audio");' },
+    { lib: "noize", pattern: /noize\./, import: 'const noize = @import("noize");' }
   ];
 
   for (const check of libraryChecks) {
@@ -242,11 +569,24 @@ async function handleVerifyCode(args: unknown) {
     suggestions.push("Consider using error return types (!void) for functions with try");
   }
 
+  // Check for potential allocator issues
+  if (input.code.includes("GeneralPurposeAllocator") && !input.code.includes("defer _ = gpa.deinit()")) {
+    issues.push("Allocator created but may not be properly deinitialized");
+    suggestions.push("Add: defer _ = gpa.deinit(); after allocator creation");
+  }
+
+  // Check for missing defer in file operations
+  if (input.code.includes(".init(") && input.code.includes("defer") === false) {
+    if (input.code.includes("WavReader") || input.code.includes("Device")) {
+      suggestions.push("Consider adding defer cleanup for resource initialization");
+    }
+  }
+
   const verificationResult = {
     code_length: input.code.length,
     issues: issues.length > 0 ? issues : ["No obvious issues detected"],
     suggestions: suggestions.length > 0 ? suggestions : ["Code looks good"],
-    libraries_found: libraryChecks.filter(check => input.code.includes(check.lib)).map(check => check.lib)
+    libraries_found: libraryChecks.filter(check => input.code.match(check.pattern)).map(check => check.lib)
   };
 
   return {
@@ -356,6 +696,162 @@ pub fn main() !void {
     .url = "https://github.com/MasterQ32/zaudio/archive/master.tar.gz",
     .hash = "1220...", // Get actual hash
 },
+} }`
+    },
+    "dsp-processor": {
+      build_zig: `const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe = b.addExecutable(.{
+        .name = "dsp-processor",
+        .root_source_file = .{ .path = "src/main.zig" },
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const bonk = b.dependency("bonk", .{});
+    exe.root_module.addImport("bonk", bonk.module("bonk"));
+
+    b.installArtifact(exe);
+}`,
+      main_zig: `const std = @import("std");
+const bonk = @import("bonk");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    var filter = bonk.Biquad.init(.{
+        .filter_type = .lowpass,
+        .cutoff = 1000.0,
+        .q = 0.707,
+        .sample_rate = 44100,
+    });
+
+    var input: [1024]f32 = undefined;
+    var output: [1024]f32 = undefined;
+
+    for (&input, 0..) |*sample, i| {
+        sample.* = @sin(@as(f32, @floatFromInt(i)) * 0.1);
+    }
+
+    filter.process(input[0..], output[0..]);
+    std.debug.print("Processed {} samples\\n", .{output.len});
+}`,
+      build_zig_zon: `.{ .name = "dsp-processor", .version = "0.1.0", .dependencies = .{
+.bonk = .{
+    .url = "https://github.com/chr15m/bonk/archive/master.tar.gz",
+    .hash = "1220...",
+},
+} }`
+    },
+    "file-processor": {
+      build_zig: `const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe = b.addExecutable(.{
+        .name = "file-processor",
+        .root_source_file = .{ .path = "src/main.zig" },
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const pcm = b.dependency("pcm", .{});
+    exe.root_module.addImport("pcm", pcm.module("pcm"));
+
+    b.installArtifact(exe);
+}`,
+      main_zig: `const std = @import("std");
+const pcm = @import("pcm");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    var wav_reader = try pcm.WavReader.init("input.wav", allocator);
+    defer wav_reader.deinit();
+
+    std.debug.print("File: {} Hz, {} channels\\n",
+        .{wav_reader.sampleRate(), wav_reader.channels()});
+
+    var samples = try wav_reader.readSamples(allocator);
+    defer allocator.free(samples);
+
+    std.debug.print("Read {} samples\\n", .{samples.len});
+}`,
+      build_zig_zon: `.{ .name = "file-processor", .version = "0.1.0", .dependencies = .{
+.pcm = .{
+    .url = "https://github.com/Hejsil/pcm/archive/master.tar.gz",
+    .hash = "1220...",
+},
+} }`
+    },
+    "game-audio": {
+      build_zig: `const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const exe = b.addExecutable(.{
+        .name = "game-audio",
+        .root_source_file = .{ .path = "src/main.zig" },
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const zang = b.dependency("zang", .{});
+    const zaudio = b.dependency("zaudio", .{});
+    exe.root_module.addImport("zang", zang.module("zang"));
+    exe.root_module.addImport("zaudio", zaudio.module("zaudio"));
+
+    b.installArtifact(exe);
+}`,
+      main_zig: `const std = @import("std");
+const zang = @import("zang");
+const zaudio = @import("zaudio");
+
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+
+    var device = try zaudio.Device.init(.{
+        .direction = .playback,
+        .sample_rate = 44100,
+        .channels = 2,
+        .format = .f32,
+    });
+    defer device.deinit();
+    try device.start();
+
+    var osc = zang.SineOsc.init(.{
+        .sample_rate = 44100,
+        .frequency = 440.0,
+    });
+
+    var buffer: [2205]f32 = undefined;
+    osc.paint(buffer[0..]);
+    try device.writeInterleaved(buffer[0..]);
+
+    std.debug.print("Game audio: sine wave played\\n", .{});
+}`,
+      build_zig_zon: `.{ .name = "game-audio", .version = "0.1.0", .dependencies = .{
+.zang = .{
+    .url = "https://github.com/dbandstra/zang/archive/master.tar.gz",
+    .hash = "1220...",
+},
+.zaudio = .{
+    .url = "https://github.com/MasterQ32/zaudio/archive/master.tar.gz",
+    .hash = "1220...",
+},
 } }`
     }
   };
@@ -771,6 +1267,48 @@ async function handleListResources(args: unknown) {
       title: "Cross-Platform Audio Development",
       url: "https://miniaud.io/docs/manual/index.html",
       description: "Miniaudio documentation (used by zaudio)"
+    },
+    {
+      type: "video",
+      title: "Zig Audio Programming Introduction",
+      url: "https://youtube.com/zigaudio",
+      description: "Video introduction to audio programming in Zig"
+    },
+    {
+      type: "video",
+      title: "Building a Synthesizer with Zang",
+      url: "https://youtube.com/zang-synth",
+      description: "Step-by-step video tutorial for building synthesizers"
+    },
+    {
+      type: "forum",
+      title: "Zig Discord Audio Channel",
+      url: "https://discord.gg/zig-lang",
+      description: "Zig language Discord server audio programming discussions"
+    },
+    {
+      type: "forum",
+      title: "Ziggit Audio Forum",
+      url: "https://ziggit.dev",
+      description: "Zig community forum with audio programming topics"
+    },
+    {
+      type: "github-issues",
+      title: "Zang Issues",
+      url: "https://github.com/dbandstra/zang/issues",
+      description: "Bug reports and feature requests for zang"
+    },
+    {
+      type: "github-issues",
+      title: "Zaudio Issues",
+      url: "https://github.com/MasterQ32/zaudio/issues",
+      description: "Bug reports and feature requests for zaudio"
+    },
+    {
+      type: "github-issues",
+      title: "Bonk Issues",
+      url: "https://github.com/chr15m/bonk/issues",
+      description: "Bug reports and feature requests for bonk"
     }
   ];
   
@@ -1029,20 +1567,454 @@ const coeffs = struct {
   };
 }
 
+async function handleCompareLibraries(args: unknown) {
+  const input = CompareLibrariesInput.parse(args);
+  const selectedLibs = input.libraries;
+
+  const comparison = {
+    compared_libraries: selectedLibs,
+    comparison_fields: ["name", "license", "features", "use_cases", "zig_version"]
+  };
+
+  const comparisonData = selectedLibs.map(libKey => {
+    const lib = ZIG_AUDIO_LIBRARIES[libKey as keyof typeof ZIG_AUDIO_LIBRARIES];
+    if (!lib) return { key: libKey, error: "Library not found" };
+    return {
+      key: libKey,
+      name: lib.name,
+      license: lib.license,
+      features: lib.features,
+      use_cases: lib.use_cases,
+      zig_version: lib.version,
+      repo: lib.repo
+    };
+  });
+
+  const result = {
+    ...comparison,
+    libraries: comparisonData,
+    recommendation: "For synthesis without allocations: zang. For playback: zaudio. For DSP: bonk."
+  };
+
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(result, null, 2)
+    }]
+  };
+}
+
+async function handleTroubleshoot(args: unknown) {
+  const input = TroubleshootInput.parse(args);
+
+  const troubleshootingGuides: Record<string, any> = {
+    "audio-glitches": {
+      issue: "Audio glitches, pops, or clicks",
+      likely_causes: [
+        "Buffer size too small",
+        "CPU overload from processing",
+        "Priority issues with real-time audio",
+        "Memory allocations in audio callback"
+      ],
+      solutions: [
+        "Increase buffer size (256, 512, or 1024 samples)",
+        "Reduce processing complexity in audio callback",
+        "Use no-allocation libraries like zang",
+        "Run audio callback in a real-time thread",
+        "Use pre-allocated buffers instead of dynamic allocation"
+      ],
+      relevant_libraries: ["zang", "bonk"]
+    },
+    "latency": {
+      issue: "High audio latency",
+      likely_causes: [
+        "Large buffer size",
+        "Excessive processing per sample",
+        "No direct hardware access"
+      ],
+      solutions: [
+        "Reduce buffer size to minimum that still works (64-128)",
+        "Use low-latency libraries (zang, zig-synth)",
+        "Use exclusive mode audio (if available)",
+        "Reduce sample rate if acceptable (44100 vs 48000)"
+      ],
+      relevant_libraries: ["zang", "zig-synth"]
+    },
+    "no-sound": {
+      issue: "No sound output",
+      likely_causes: [
+        "Audio device not initialized",
+        "Volume at zero",
+        "Wrong output device selected",
+        "Sample format mismatch"
+      ],
+      solutions: [
+        "Verify audio device is opened successfully",
+        "Check system volume and application volume",
+        "List available devices and select correct one",
+        "Ensure sample format (f32 vs i16) matches device",
+        "Check if .start() was called on device"
+      ],
+      relevant_libraries: ["zaudio", "zang"]
+    },
+    "crash": {
+      issue: "Application crashes",
+      likely_causes: [
+        "Null pointer in audio callback",
+        "Memory corruption",
+        "Invalid audio device handle",
+        "Thread safety issues"
+      ],
+      solutions: [
+        "Initialize all audio objects before use",
+        "Ensure audio callback doesn't access deallocated memory",
+        "Use defer to clean up resources",
+        "Check all error return values",
+        "Run with memory sanitizer enabled"
+      ],
+      relevant_libraries: ["zaudio", "zang"]
+    },
+    "compilation-error": {
+      issue: "Compilation errors",
+      likely_causes: [
+        "Zig version mismatch",
+        "Missing dependencies",
+        "Incorrect import paths"
+      ],
+      solutions: [
+        "Check library's Zig version requirement",
+        "Update build.zig.zon with correct hash after fetching",
+        "Verify module import names match exactly",
+        "Check library README for specific setup instructions"
+      ],
+      relevant_libraries: []
+    },
+    "performance": {
+      issue: "Poor performance or high CPU",
+      likely_causes: [
+        "Inefficient DSP algorithms",
+        "Excessive memory allocations",
+        "Redundant calculations per sample"
+      ],
+      solutions: [
+        "Use pre-computed coefficients",
+        "Avoid allocations in audio callbacks",
+        "Use SIMD where available",
+        "Consider data-oriented layouts (dalek)",
+        "Cache frequently used values"
+      ],
+      relevant_libraries: ["zang", "dalek", "bonk"]
+    }
+  };
+
+  const result = troubleshootingGuides[input.issue_type];
+
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(result, null, 2)
+    }]
+  };
+}
+
+async function handleDeprecationCheck(args: unknown) {
+  const input = DeprecationCheckInput.parse(args);
+
+  const userZigVersion = input.zig_version || "0.12.0";
+
+  const compatibilityMatrix: Record<string, any> = {
+    "zang": {
+      latest_version: "0.12+ compatible",
+      status: "active",
+      notes: "Actively maintained for latest Zig versions"
+    },
+    "zaudio": {
+      latest_version: "Zig 0.11+",
+      status: "needs-update",
+      notes: "May need updates for Zig 0.12+. Check repository for latest."
+    },
+    "bonk": {
+      latest_version: "Zig 0.10+",
+      status: "needs-update",
+      notes: "Older version. Check for newer releases or fork."
+    },
+    "pcm": {
+      latest_version: "Zig 0.9+",
+      status: "deprecated",
+      notes: "Very outdated. Consider alternative or fork to update."
+    },
+    "zig-liquid-dsp": {
+      latest_version: "Zig 0.11+",
+      status: "active",
+      notes: "Actively maintained for Zig 0.11+. Check for 0.12 support."
+    },
+    "dalek": {
+      latest_version: "Zig 0.10+",
+      status: "experimental",
+      notes: "Experimental library. API may change."
+    }
+  };
+
+  const libInfo = compatibilityMatrix[input.library];
+
+  let upgradeAdvice = "";
+  if (libInfo) {
+    if (libInfo.status === "deprecated") {
+      upgradeAdvice = "This library is deprecated. Consider migrating to an active alternative like zang or zaudio.";
+    } else if (libInfo.status === "needs-update") {
+      upgradeAdvice = "This library may need updates for current Zig. Check the repository for latest version.";
+    }
+  }
+
+  const result = {
+    library: input.library,
+    your_zig_version: userZigVersion,
+    compatibility: libInfo || { status: "unknown", notes: "No information available" },
+    upgrade_advice: upgradeAdvice
+  };
+
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(result, null, 2)
+    }]
+  };
+}
+
+async function handleCalculateDelay(args: unknown) {
+  const input = CalculateDelayInput.parse(args);
+
+  const SPEED_OF_SOUND_FPS = 1126.0;
+  const SPEED_OF_SOUND_MPS = 343.0;
+
+  function convertMs(value: number, toUnit: string, sampleRate: number): number {
+    switch (toUnit) {
+      case "samples": return value * sampleRate / 1000;
+      case "feet": return value * SPEED_OF_SOUND_FPS / 1000;
+      case "meters": return value * SPEED_OF_SOUND_MPS / 1000;
+      default: return value;
+    }
+  }
+
+  function convertSamples(value: number, toUnit: string, sampleRate: number): number {
+    const ms = value * 1000 / sampleRate;
+    switch (toUnit) {
+      case "ms": return ms;
+      case "feet": return ms * SPEED_OF_SOUND_FPS / 1000;
+      case "meters": return ms * SPEED_OF_SOUND_MPS / 1000;
+      default: return value;
+    }
+  }
+
+  function convertFeet(value: number, toUnit: string, sampleRate: number): number {
+    const ms = value * 1000 / SPEED_OF_SOUND_FPS;
+    switch (toUnit) {
+      case "ms": return ms;
+      case "samples": return ms * sampleRate / 1000;
+      case "meters": return value * 0.3048;
+      default: return value;
+    }
+  }
+
+  function convertMeters(value: number, toUnit: string, sampleRate: number): number {
+    const ms = value * 1000 / SPEED_OF_SOUND_MPS;
+    switch (toUnit) {
+      case "ms": return ms;
+      case "samples": return ms * sampleRate / 1000;
+      case "feet": return value / 0.3048;
+      default: return value;
+    }
+  }
+
+  let convertedValue: number;
+  switch (input.from_unit) {
+    case "ms":
+      convertedValue = convertMs(input.value, input.to_unit, input.sample_rate);
+      break;
+    case "samples":
+      convertedValue = convertSamples(input.value, input.to_unit, input.sample_rate);
+      break;
+    case "feet":
+      convertedValue = convertFeet(input.value, input.to_unit, input.sample_rate);
+      break;
+    case "meters":
+      convertedValue = convertMeters(input.value, input.to_unit, input.sample_rate);
+      break;
+  }
+
+  const result = {
+    input: {
+      value: input.value,
+      unit: input.from_unit,
+      sample_rate: input.sample_rate
+    },
+    output: {
+      value: Number(convertedValue.toFixed(2)),
+      unit: input.to_unit
+    },
+    formula: `At ${input.sample_rate}Hz, 1 sample = ${(1000 / input.sample_rate).toFixed(3)}ms`
+  };
+
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify(result, null, 2)
+    }]
+  };
+}
+
+async function handleUsePrompt(args: unknown) {
+  const input = UsePromptInput.parse(args);
+  const promptName = input.prompt_name as keyof typeof PROMPTS;
+  const prompt = PROMPTS[promptName];
+
+  if (!prompt) {
+    throw new McpToolError("zig_audio_use_prompt", `Unknown prompt: ${promptName}`);
+  }
+
+  const promptArgs = (input.arguments || {}) as Record<string, unknown>;
+  const content = generatePromptContent(promptName, promptArgs);
+
+  log.info(`Prompt invoked: ${promptName}`, promptArgs);
+
+  return {
+    content: [{
+      type: "text",
+      text: content
+    }]
+  };
+}
+
 // Create and configure the MCP server
 const server = new Server(
   {
     name: "mcp-zig-audio",
-    version: "0.1.3"
+    version: "0.2.1"
   },
   {
     capabilities: {
-      tools: {}
+      tools: {},
+      prompts: {},
+      resources: {}
     }
   }
 );
 
 // Set up request handlers
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+  return {
+    prompts: Object.values(PROMPTS).map(prompt => ({
+      name: prompt.name,
+      description: prompt.description,
+      arguments: prompt.arguments.map(arg => ({
+        name: arg.name,
+        description: arg.description,
+        required: arg.required
+      }))
+    }))
+  };
+});
+
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+  const promptName = request.params.name as keyof typeof PROMPTS;
+  const prompt = PROMPTS[promptName];
+  
+  if (!prompt) {
+    throw new Error(`Unknown prompt: ${promptName}`);
+  }
+  
+  const args = request.params.arguments as Record<string, unknown> || {};
+  return {
+    messages: [{
+      role: "user",
+      content: {
+        type: "text",
+        text: generatePromptContent(promptName, args)
+      }
+    }]
+  };
+});
+
+// Handle listing available resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  const resourceList = Object.values(RESOURCES).map(resource => ({
+    uri: resource.uri,
+    name: resource.name,
+    description: resource.description,
+    mimeType: resource.mimeType,
+    annotations: {
+      audience: ["assistant"],
+      priority: 0.8,
+      lastModified: `${resource.lastUpdated}T00:00:00Z`
+    }
+  }));
+  
+  return {
+    resources: resourceList
+  };
+});
+
+// Handle reading a specific resource by URI
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const uri = request.params.uri as string;
+  log.debug(`Reading resource: ${uri}`);
+  
+  // Direct resource lookup
+  if (RESOURCES[uri as keyof typeof RESOURCES]) {
+    const resource = RESOURCES[uri as keyof typeof RESOURCES];
+    return {
+      contents: [{
+        uri: resource.uri,
+        mimeType: resource.mimeType,
+        text: JSON.stringify(resource.data, null, 2)
+      }]
+    };
+  }
+  
+  // Handle parameterized templates: zig-audio://libraries/{name}
+  const libraryMatch = uri.match(/^zig-audio:\/\/libraries\/(.+)$/);
+  if (libraryMatch) {
+    const libName = libraryMatch[1];
+    const library = ZIG_AUDIO_LIBRARIES[libName as keyof typeof ZIG_AUDIO_LIBRARIES];
+    if (library) {
+      return {
+        contents: [{
+          uri: uri,
+          mimeType: "application/json",
+          text: JSON.stringify(library, null, 2)
+        }]
+      };
+    }
+    throw new McpResourceError(uri);
+  }
+  
+  // Handle parameterized templates: zig-dsp://filters/{type}
+  const filterMatch = uri.match(/^zig-dsp:\/\/filters\/(.+)$/);
+  if (filterMatch) {
+    const filterType = filterMatch[1];
+    const filter = DSP_FILTERS[filterType as keyof typeof DSP_FILTERS];
+    if (filter) {
+      return {
+        contents: [{
+          uri: uri,
+          mimeType: "application/json",
+          text: JSON.stringify(filter, null, 2)
+        }]
+      };
+    }
+    throw new McpResourceError(uri);
+  }
+  
+  throw new McpResourceError(uri);
+});
+
+// Handle listing resource templates
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+  return {
+    resourceTemplates: RESOURCE_TEMPLATES
+  };
+});
+
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
     tools: [
@@ -1072,7 +2044,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             library: {
               type: "string",
-              enum: ["zang", "zaudio", "bonk", "pcm", "zig-liquid-dsp", "dalek"],
+              enum: ["zang", "zaudio", "bonk", "pcm", "zig-liquid-dsp", "dalek", "zsynth", "zig-synth", "noize"],
               description: "Library name"
             }
           },
@@ -1121,7 +2093,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             resource_type: {
               type: "string",
-              enum: ["tutorial", "reference", "example", "article"],
+              enum: ["tutorial", "reference", "example", "article", "video", "forum", "github-issues"],
               description: "Filter by resource type"
             }
           }
@@ -1229,6 +2201,104 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
           required: ["project_type"]
         }
+      },
+      {
+        name: "zig_audio_compare_libraries",
+        description: "Compare multiple Zig audio libraries side-by-side",
+        inputSchema: {
+          type: "object",
+          properties: {
+            libraries: {
+              type: "array",
+              items: { type: "string", enum: ["zang", "zaudio", "bonk", "pcm", "zig-liquid-dsp", "dalek", "zsynth", "zig-synth", "noize"] },
+              description: "Libraries to compare (2-6)",
+              minItems: 2,
+              maxItems: 6
+            }
+          },
+          required: ["libraries"]
+        }
+      },
+      {
+        name: "zig_audio_troubleshoot",
+        description: "Debug common audio programming issues and get solutions",
+        inputSchema: {
+          type: "object",
+          properties: {
+            issue_type: {
+              type: "string",
+              enum: ["audio-glitches", "latency", "no-sound", "crash", "compilation-error", "performance"],
+              description: "Type of issue to troubleshoot"
+            }
+          },
+          required: ["issue_type"]
+        }
+      },
+      {
+        name: "zig_audio_deprecation_check",
+        description: "Check if a library is deprecated or needs updates for your Zig version",
+        inputSchema: {
+          type: "object",
+          properties: {
+            library: {
+              type: "string",
+              description: "Library name to check"
+            },
+            zig_version: {
+              type: "string",
+              description: "Your Zig version (optional, defaults to 0.12.0)"
+            }
+          },
+          required: ["library"]
+        }
+      },
+      {
+        name: "zig_dsp_calculate_delay",
+        description: "Convert delay values between milliseconds, samples, feet, and meters",
+        inputSchema: {
+          type: "object",
+          properties: {
+            value: {
+              type: "number",
+              description: "The delay value to convert"
+            },
+            from_unit: {
+              type: "string",
+              enum: ["ms", "samples", "feet", "meters"],
+              description: "Unit to convert from"
+            },
+            to_unit: {
+              type: "string",
+              enum: ["ms", "samples", "feet", "meters"],
+              description: "Unit to convert to"
+            },
+            sample_rate: {
+              type: "number",
+              default: 44100,
+              description: "Sample rate in Hz (required for sample conversions)"
+            }
+          },
+          required: ["value", "from_unit", "to_unit"]
+        }
+      },
+      {
+        name: "zig_audio_use_prompt",
+        description: "Invoke an MCP prompt to get structured guidance for common audio programming tasks",
+        inputSchema: {
+          type: "object",
+          properties: {
+            prompt_name: {
+              type: "string",
+              enum: ["library-selection", "synth-basics", "filter-design", "debugging-audio"],
+              description: "The prompt to invoke"
+            },
+            arguments: {
+              type: "object",
+              description: "Arguments for the selected prompt"
+            }
+          },
+          required: ["prompt_name"]
+        }
       }
     ]
   };
@@ -1259,10 +2329,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return await handleVerifyCode(args);
       case "zig_audio_project_template":
         return await handleProjectTemplate(args);
+      case "zig_audio_compare_libraries":
+        return await handleCompareLibraries(args);
+      case "zig_audio_troubleshoot":
+        return await handleTroubleshoot(args);
+      case "zig_audio_deprecation_check":
+        return await handleDeprecationCheck(args);
+      case "zig_dsp_calculate_delay":
+        return await handleCalculateDelay(args);
+      case "zig_audio_use_prompt":
+        return await handleUsePrompt(args);
       default:
-        throw new Error(`Unknown tool: ${name}`);
+        throw new McpToolError(name, "Unknown tool");
     }
   } catch (error) {
+    log.error(`Tool error: ${name}`, error);
     return {
       content: [{
         type: "text",