MCP Zig Audio

A Model Context Protocol (MCP) server that provides AI assistance for writing high-quality Zig code focused on pro-audio and DSP algorithms.

Overview

MCP Zig Audio is an MCP server that helps LLMs, AI agents, and developers write better Zig code for audio programming, digital signal processing (DSP), and synthesizer development. It provides tools and resources for discovering audio libraries, understanding DSP concepts, explaining filter algorithms, generating starter code, and troubleshooting common issues.

Key Features

• Library Discovery - Browse and filter through 9 major Zig audio/DSP libraries
• Smart Recommendations - Get library suggestions based on your specific audio programming needs
• DSP Filter Design - Interactive filter design with coefficient calculation and stability checks
• Code Generation - Generate starter code for oscillators, envelopes, filters, delay lines, and more
• Code Verification - Check Zig code for common issues and missing imports
• Project Templates - Generate complete project skeletons with build files
• Learning Resources - Curated tutorials, examples, and documentation references
• Core Concepts - Explanations of fundamental audio/DSP terminology
• Troubleshooting - Debug common audio programming issues with solutions
• MCP Resources - Direct access to reference data via MCP resource URIs

Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• npm or pnpm

Installation

# Clone the repository
git clone https://github.com/ray0404/zig-audio-mcp.git
cd zig-audio-mcp

# Install dependencies
npm install

# Build the TypeScript project
npm run build

Running the Server

# Using stdio transport (default)
npm start

# Or run in development mode with auto-reload
npm run dev

Connecting via MCP Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/index.js"]
});

const client = new Client({
  name: "my-client",
  version: "1.0.0"
}, {
  capabilities: {}
});

await client.connect(transport);

// List available tools
const tools = await client.request(
  { method: "tools/list", params: {} },
  {}
);

console.log(tools);

Available Tools

1. zig_audio_list_libraries

Lists available Zig audio/DSP libraries with optional filtering by category or feature.

Parameters:

• category (optional): Filter by category (synthesis, effects, filters, dsp, playback, recording, file-io, encoding, sdr, engine, wrapper, experimental, all)
• feature (optional): Filter by feature keyword

Example:

{
  "name": "zig_audio_list_libraries",
  "arguments": {
    "category": "synthesis"
  }
}

2. zig_audio_library_info

Gets detailed information about a specific Zig audio library.

Parameters:

• library (required): Library name (zang, zaudio, bonk, pcm, zig-liquid-dsp, dalek, zsynth, zig-synth, noize)

Example:

{
  "name": "zig_audio_library_info",
  "arguments": {
    "library": "zang"
  }
}

3. zig_dsp_explain_filter

Explains a DSP filter type with its mathematical formula, use cases, and compatible Zig libraries.

Parameters:

• filter_type (required): Filter type (lowpass, highpass, bandpass, notch, biquad, one-pole)

Example:

{
  "name": "zig_dsp_explain_filter",
  "arguments": {
    "filter_type": "lowpass"
  }
}

4. zig_audio_generate_code

Generates starter code for common audio/DSP tasks in Zig.

Parameters:

• task (required): Type of code to generate (oscillator, envelope, filter, delay, mixer, player, recorder, file-write, file-read)
• parameters (optional): Additional parameters for code generation

Example:

{
  "name": "zig_audio_generate_code",
  "arguments": {
    "task": "oscillator"
  }
}

5. zig_audio_list_resources

Lists learning resources for Zig audio development.

Parameters:

• resource_type (optional): Filter by type (tutorial, reference, example, article)

6. zig_dsp_get_concepts

Returns explanations of fundamental audio/DSP concepts including sample rate, bit depth, buffer size, Nyquist frequency, and aliasing.

7. zig_audio_recommend_library

Get intelligent library recommendations based on your audio programming use case and requirements.

Parameters:

• use_case (required): Description of what you're building (e.g., "synthesizer", "audio player", "DSP effects")
• requirements (optional): Specific requirements like "low latency", "no allocations", "cross-platform"

Example:

{
  "name": "zig_audio_recommend_library",
  "arguments": {
    "use_case": "building a real-time synthesizer",
    "requirements": ["low latency", "no dynamic allocations"]
  }
}

8. zig_dsp_design_filter

Design DSP filters and calculate biquad coefficients with stability verification.

Parameters:

• filter_type (required): Filter type (lowpass, highpass, bandpass, notch)
• parameters (required): Filter parameters including sample_rate, cutoff frequency, Q factor

Example:

{
  "name": "zig_dsp_design_filter",
  "arguments": {
    "filter_type": "lowpass",
    "parameters": {
      "sample_rate": 44100,
      "cutoff": 1000,
      "q": 0.707
    }
  }
}

9. zig_audio_verify_code

Verify Zig code for basic syntax issues, missing imports, and common mistakes.

Parameters:

• code (required): Zig code to analyze
• libraries (optional): Expected libraries that should be imported

Example:

{
  "name": "zig_audio_verify_code",
  "arguments": {
    "code": "const zang = @import(\"zang\"); var osc = zang.SineOsc.init();"
  }
}

10. zig_audio_project_template

Generate complete project templates for different types of audio applications.

Parameters:

• project_type (required): Type of project (synthesizer, audio-player, dsp-processor, file-processor, game-audio)
• features (optional): Additional features to include

Example:

{
  "name": "zig_audio_project_template",
  "arguments": {
    "project_type": "synthesizer"
  }
}

11. zig_audio_compare_libraries

Compare multiple Zig audio libraries side-by-side.

Parameters:

• libraries (required): Array of library names to compare (2-6 libraries)

12. zig_audio_troubleshoot

Debug common audio programming issues and get solutions.

Parameters:

• issue_type (required): Type of issue (audio-glitches, latency, no-sound, crash, compilation-error, performance)

13. zig_audio_deprecation_check

Check if a library is deprecated or needs updates for your Zig version.

Parameters:

• library (required): Library name to check
• zig_version (optional): Your Zig version (defaults to 0.12.0)

14. zig_dsp_calculate_delay

Convert delay values between milliseconds, samples, feet, and meters.

Parameters:

• value (required): The delay value to convert
• from_unit (required): Unit to convert from (ms, samples, feet, meters)
• to_unit (required): Unit to convert to (ms, samples, feet, meters)
• sample_rate (optional): Sample rate in Hz (defaults to 44100)

MCP Resources

The server exposes 8 static resources + 2 parameterized templates for direct context access:

Static Resources

| URI | Name | Content | |-----|------|---------| | zig-audio://libraries | Zig Audio Libraries | Complete database of 9 libraries | | zig-dsp://filters | DSP Filter Reference | 6 filter types with formulas | | zig-dsp://concepts | Audio/DSP Concepts | 5 fundamental concepts | | zig-audio://templates/code | Code Templates | 9 code snippets | | zig-audio://templates/project | Project Templates | 5 project skeletons | | zig-audio://resources | Learning Resources | 11 tutorials/references | | zig-audio://troubleshooting | Troubleshooting Guide | 6 issue types with solutions | | zig-audio://compatibility | Compatibility Matrix | Library version info |

Parameterized Templates

| URI Template | Purpose | |--------------|---------| | zig-audio://libraries/{name} | Individual library details (zang, zaudio, etc.) | | zig-dsp://filters/{type} | Individual filter details (lowpass, highpass, etc.) |

Supported Zig Libraries

zang

• Description: Audio synthesis library with generators, effects, and filters
• License: MIT
• Features: Oscillators, envelopes, filters, effects, no dynamic allocations
• Repository: https://github.com/Hejsil/zang

zaudio

• Description: Zig wrapper for miniaudio
• License: MIT
• Features: Playback, recording, node graph, streaming
• Repository: https://github.com/MasterQ32/zaudio

bonk

• Description: DSP objects including filters and delay lines
• License: MPL-2.0
• Features: Filters, delay lines, waveshapers
• Repository: https://github.com/chr15m/bonk

pcm

• Description: PCM audio file handling for WAV and AIFF
• License: MIT
• Features: WAV, AIFF, I/O, encoding
• Repository: https://github.com/Hejsil/pcm

zig-liquid-dsp

• Description: DSP library for software-defined radio
• License: MIT
• Features: Filters, modulation, Fourier, SDR
• Repository: https://github.com/ggerard/zig-liquid-dsp

dalek

• Description: Experimental data-oriented audio engine
• License: MIT
• Features: Data-oriented design, performance optimization
• Repository: https://github.com/chr15m/dalek

zsynth

• Description: Simple FM synthesis library for Zig
• License: MIT
• Features: FM synthesis, operators, modulation
• Repository: https://github.com/zsynth/zsynth

zig-synth

• Description: Zig wrapper for sokol_audio for low-latency audio
• License: MIT
• Features: Low-latency, sokol, playback
• Repository: https://github.com/zig-synth/zig-synth

noize

• Description: Simple audio synthesis library with a focus on ease of use
• License: MIT
• Features: Synthesis, generators, noise
• Repository: https://github.com/noize/noize

DSP Filter Reference

Low Pass Filter

Allows frequencies below the cutoff to pass through, attenuating higher frequencies.

Formula: y[n] = a0 * x[n] + a1 * x[n-1] + a2 * x[n-2] - b1 * y[n-1] - b2 * y[n-2]

Use Cases: Sub-bass smoothing, removing high-frequency noise, warmth/room modeling

Zig Libraries: zang, bonk, zig-liquid-dsp

High Pass Filter

Allows frequencies above the cutoff to pass through, attenuating lower frequencies.

Use Cases: DC offset removal, rumble removal, clarifying midrange

Zig Libraries: zang, bonk, zig-liquid-dsp

Band Pass Filter

Allows frequencies within a specific band to pass through.

Use Cases: Isolating instrument frequencies, telephone effect, formant simulation

Notch Filter

Attenuates a specific frequency band while allowing others to pass.

Use Cases: Hum removal, feedback suppression, EQ notching

Biquad Filter

Second-order IIR filter using two poles and two zeros. Generic form for many filter types.

Use Cases: Parametric EQ, crossover filters, tone control

One-Pole Filter

Simple first-order filter with single pole. Good for smoothing and DC removal.

Use Cases: Smoothing, DC removal, simple envelopes

Audio/DSP Concepts

Sample Rate

Number of samples captured per second (e.g., 44100 Hz, 48000 Hz).

• Typical Values: 44100, 48000, 96000
• Impact: Higher rates = more accurate audio but more CPU/memory

Bit Depth

Number of bits per sample for amplitude resolution.

• Typical Values: 16, 24, 32
• Impact: Higher depth = more dynamic range, less quantization noise

Buffer Size

Number of samples processed per callback cycle.

• Typical Values: 64, 128, 256, 512, 1024
• Impact: Smaller = lower latency, higher CPU; larger = more stable, more latency

Nyquist Frequency

Maximum representable frequency (sample_rate / 2).

• Formula: f_nyquist = sample_rate / 2

Aliasing

Distortion from sampling frequencies above Nyquist.

• Prevention: Use anti-aliasing filters before downsampling

Architecture

Project Structure

mcp-zig-audio/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── test.ts           # Evaluation test suite
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
└── evaluation.xml        # Evaluation Q&A pairs

Technology Stack

• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod
• Transport: Stdio (default), Streamable HTTP

MCP Protocol Integration

The server implements the MCP specification using:

• Server class from @modelcontextprotocol/sdk/server/index.js
• StdioServerTransport for stdio communication
• Zod schemas for input validation
• JSON-RPC 2.0 message format

Development

Building

npm run build

Running Tests

npx tsx src/test.ts

Development Mode

npm run dev

This runs the server with tsx for auto-reloading on file changes.

Evaluation

The project includes an evaluation suite in evaluation.xml with Q&A pairs to verify the MCP server correctly answers questions about Zig audio programming.

To run evaluation tests:

npx tsx src/test.ts

Expected output:

• All 30 tests should pass
• Tests cover tool listing, library discovery, filter explanations, code generation, concept queries, and MCP resource access

Use Cases

For AI Assistants

When helping users write Zig audio code, use this MCP server to:

1. Discover Libraries - Find appropriate libraries for the task
2. Understand Concepts - Explain DSP fundamentals
3. Generate Code - Create starter implementations
4. Filter Selection - Choose the right filter algorithm
5. Find Resources - Locate learning materials

For Developers

• Quick reference for Zig audio libraries
• Understanding DSP algorithms and their implementations
• Generating boilerplate code for audio projects
• Learning about audio programming concepts

License

MIT

Contributing

Contributions are welcome! Please ensure:

1. Tests pass: npx tsx src/test.ts
2. Build succeeds: npm run build
3. New features include Zod validation schemas
4. Tools follow the naming convention: zig_audio_* or zig_dsp_*