npm package: @ray0404/zig-audio-mcp
Description: MCP server for Zig audio/DSP programming assistance - run with: npx @ray0404/zig-audio-mcp
Author: ray0404
Latest version: 0.2.1

# 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

```bash
# 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

```bash
# Using stdio transport (default)
npm start

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

### Connecting via MCP Client

```typescript
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```bash
npm run build
```

### Running Tests

```bash
npx tsx src/test.ts
```

### Development Mode

```bash
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:

```bash
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_*`