@ray0404/zig-audio-mcp 0.1.0

package/README.md

@@ -0,0 +1,444 @@
+# 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 for discovering audio libraries, understanding DSP concepts, explaining filter algorithms, and generating starter code.
+
+## Key Features
+
+- **Library Discovery** - Browse and filter through 6 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
+
+## 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)
+
+**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"
+  }
+}
+```
+
+## 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
+
+## 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 10 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 9 tests should pass
+- Tests cover tool listing, library discovery, filter explanations, code generation, and concept queries
+
+## 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_*`
+

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}