@ray0404/zig-audio-mcp 0.1.0

package/AGENTS.md

@@ -0,0 +1,302 @@
+# Zig-Audio MCP Server | Project Context and Instructions
+
+## Project Goal
+
+Build an MCP (Model Context Protocol) server that communicates with either local and/or remote resources in order to aid users, **LLMs/Agents**, etc, in writing high-quality `zig` code, with an emphasis in pro-audio/DSP algorithms.
+
+## Project Overview
+
+This is a Node.js/TypeScript project that implements an MCP server to help AI systems assist developers in writing Zig audio and DSP code. The server provides tools for:
+
+- Discovering and learning about Zig audio/DSP libraries
+- Understanding DSP filter algorithms and their implementations
+- Generating starter code for common audio programming tasks
+- Learning fundamental audio/DSP concepts
+- Finding resources for further learning
+
+## Technology Stack
+
+- **Language:** TypeScript
+- **MCP SDK:** @modelcontextprotocol/sdk ^1.0.0
+- **Validation:** Zod ^3.22.4
+- **Runtime:** Node.js 18+
+- **Transport:** Stdio (default), supports Streamable HTTP
+
+## Project Structure
+
+```
+MCP_Zig/
+├── src/
+│   ├── index.ts          # Main MCP server implementation
+│   └── test.ts           # Evaluation tests
+├── dist/                 # Compiled JavaScript
+├── package.json          # Dependencies and scripts
+├── tsconfig.json         # TypeScript configuration
+├── README.md             # Project documentation
+├── AGENTS.md             # This file
+├── evaluation.xml        # Evaluation Q&A pairs
+└── GEMINI.md             # AI/LLM context
+```
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm install` | Install dependencies |
+| `npm run build` | Compile TypeScript to JavaScript |
+| `npm start` | Run the MCP server |
+| `npm run dev` | Run in development mode with auto-reload |
+| `npx tsx src/test.ts` | Run evaluation tests |
+
+## MCP Tools
+
+The server exposes 10 tools for AI assistants:
+
+### 1. zig_audio_list_libraries
+List available Zig audio/DSP libraries with optional filtering.
+
+### 2. zig_audio_library_info
+Get detailed information about a specific library (zang, zaudio, bonk, pcm, zig-liquid-dsp, dalek).
+
+### 3. zig_dsp_explain_filter
+Explain DSP filter types (lowpass, highpass, bandpass, notch, biquad, one-pole) with formulas and use cases.
+
+### 4. zig_audio_generate_code
+Generate starter code for audio/DSP tasks (oscillator, envelope, filter, delay, mixer, player, recorder, file operations).
+
+### 5. zig_audio_list_resources
+List learning resources (tutorials, references, examples, articles).
+
+### 6. zig_dsp_get_concepts
+Get explanations of fundamental audio/DSP concepts.
+
+### 7. zig_audio_recommend_library
+Get intelligent library recommendations based on use case and requirements.
+
+### 8. zig_dsp_design_filter
+Design DSP filters with coefficient calculation and stability verification.
+
+### 9. zig_audio_verify_code
+Verify Zig code for syntax issues and missing imports.
+
+### 10. zig_audio_project_template
+Generate complete project templates for audio applications.
+
+## Development Guidelines
+
+### MCP Protocol Compliance
+- Use `@modelcontextprotocol/sdk` for server implementation
+- Implement proper JSON-RPC 2.0 message handling
+- Use StdioServerTransport for local execution
+- Support Streamable HTTP for remote deployment
+
+### Code Quality
+- All inputs validated with Zod schemas
+- Clear tool names following `zig_audio_*` or `zig_dsp_*` convention
+- Comprehensive tool descriptions with parameter documentation
+- Proper error handling with actionable messages
+
+### Testing
+- Run evaluation tests before submitting changes
+- Ensure all tests pass: `npx tsx src/test.ts`
+- Verify build succeeds: `npm run build`
+
+## Extending the Server
+
+To add new tools:
+
+1. Define Zod input schema in the tool handler section
+2. Add tool definition in the ListToolsRequestSchema handler
+3. Implement the tool logic
+4. Add corresponding test cases
+
+## Zig Audio Ecosystem
+
+The server maintains knowledge of the Zig audio ecosystem:
+
+### Libraries
+- **zang** - Synthesis library (MIT)
+- **zaudio** - miniaudio wrapper (MIT)
+- **bonk** - DSP objects (MPL-2.0)
+- **pcm** - File I/O (MIT)
+- **zig-liquid-dsp** - SDR library (MIT)
+- **dalek** - Experimental engine (MIT)
+
+### Filter Types
+- Low pass, high pass, band pass, notch
+- Biquad, one-pole filters
+
+### Concepts
+- Sample rate, bit depth, buffer size
+- Nyquist frequency, aliasing
+
+## CI/CD and Deployment
+
+The project is designed to be deployed as:
+
+1. **Local tool** - Run via stdio transport
+2. **HTTP service** - Deploy with Streamable HTTP transport
+3. **Docker container** - Containerize for cloud deployment
+
+## Contact and Support
+
+For issues, feature requests, or contributions, please refer to the project repository.
+
+
+# GEMINI.md - AI/LLM Context for MCP Zig Audio
+
+## Project Purpose
+
+This MCP server helps AI assistants provide better assistance for writing Zig code related to audio programming and digital signal processing (DSP).
+
+## What This Server Does
+
+When an AI assistant needs to help with Zig audio/DSP programming, it can call this MCP server to:
+
+1. **Discover Libraries** - Find which Zig libraries are available for specific audio tasks
+2. **Explain Filters** - Understand how different DSP filters work mathematically
+3. **Generate Code** - Create starter implementations for common patterns
+4. **Learn Concepts** - Understand fundamental audio terminology
+5. **Find Resources** - Locate tutorials and documentation
+
+## Tool Usage Examples
+
+### Finding the Right Library
+
+**User Question:** "I want to build a synthesizer in Zig without any dynamic memory allocation. Which library should I use?"
+
+**AI Action:** Call `zig_audio_list_libraries` with feature filter or `zig_audio_library_info` for specific libraries.
+
+**Response:** The server returns information about zang, which is specifically designed for zero-allocation synthesis.
+
+### Understanding DSP Concepts
+
+**User Question:** "What is the Nyquist frequency and why does it matter for audio?"
+
+**AI Action:** Call `zig_dsp_get_concepts` to get explanations.
+
+**Response:** The server returns detailed explanations of Nyquist frequency, sample rate, aliasing, and their relationships.
+
+### Generating Code
+
+**User Question:** "Help me write a simple oscillator in Zig"
+
+**AI Action:** Call `zig_audio_generate_code` with `task: "oscillator"`
+
+**Response:** The server returns starter Zig code for implementing an oscillator.
+
+### Filter Selection
+
+**User Question:** "I need to remove DC offset from an audio signal, which filter should I use?"
+
+**AI Action:** Call `zig_dsp_explain_filter` with different filter types to find the right one.
+
+**Response:** High-pass filter or one-pole filter are suitable for DC offset removal, with explanations and formulas.
+
+### Library Recommendations
+
+**User Question:** "I want to build a cross-platform audio player in Zig. What library should I use?"
+
+**AI Action:** Call `zig_audio_recommend_library` with use_case "audio player" and requirements ["cross-platform"].
+
+**Response:** The server recommends zaudio as the primary choice, explaining it's a miniaudio wrapper perfect for cross-platform playback.
+
+### Filter Design
+
+**User Question:** "Help me design a low-pass filter at 1000 Hz for 44.1 kHz sample rate"
+
+**AI Action:** Call `zig_dsp_design_filter` with filter_type "lowpass", sample_rate 44100, cutoff 1000.
+
+**Response:** The server returns biquad coefficients, stability check, and ready-to-use Zig code.
+
+### Code Verification
+
+**User Question:** "Is this Zig code correct: const zang = @import("zang"); var osc = SineOsc{}"
+
+**AI Action:** Call `zig_audio_verify_code` with the code snippet.
+
+**Response:** The server identifies missing std import, incorrect struct usage, and suggests corrections.
+
+## Key Information for AI Assistants
+
+### Library Selection Guide
+
+| Task | Recommended Library |
+|------|-------------------|
+| Synthesis without allocations | zang |
+| Audio playback/recording | zaudio |
+| DSP filters and delay lines | bonk |
+| File I/O (WAV/AIFF) | pcm |
+| Software-defined radio | zig-liquid-dsp |
+| High-performance audio engine | dalek |
+
+### Filter Selection Guide
+
+| Goal | Filter Type |
+|------|-------------|
+| Remove high frequencies | Low Pass |
+| Remove low frequencies (DC offset) | High Pass |
+| Isolate frequency band | Band Pass |
+| Remove specific frequency (hum) | Notch |
+| General EQ/tone control | Biquad |
+| Simple smoothing | One-Pole |
+
+### Code Generation Tasks
+
+The server can generate starter code for:
+- `oscillator` - Sine, square, saw, triangle waves
+- `envelope` - ADSR envelope implementation
+- `filter` - Biquad filter implementation
+- `delay` - Delay line with feedback
+- `mixer` - Multi-channel audio mixer
+- `player` - Audio playback using zaudio
+- `recorder` - Audio recording using zaudio
+- `file-write` - Write audio to WAV file
+- `file-read` - Read audio from WAV file
+
+## Important Notes for AI Assistants
+
+1. **Zig Specifics**: Zig is a systems programming language with manual memory management. The server's library information reflects this (e.g., zang's no-allocation design).
+
+2. **Version Awareness**: The Zig audio ecosystem is actively developing. Library versions and features may change.
+
+3. **License Considerations**: Some libraries have different licenses (MIT vs MPL-2.0). This is included in library information.
+
+4. **Transport Options**: The server runs on stdio by default but can be configured for HTTP transport for remote deployment.
+
+## Error Handling
+
+When tools return errors, they provide actionable messages. Common issues:
+- Invalid library name (check enum values)
+- Missing required parameters
+- Invalid filter type
+
+## Testing the Server
+
+Before relying on this server for production tasks, AI assistants should verify functionality using the test suite:
+
+```bash
+npx tsx src/test.ts
+```
+
+This runs 9 tests covering all tool functionality.
+
+## Integration Points
+
+This MCP server is designed to work with:
+- Claude Desktop
+- Other MCP clients
+- Custom AI assistants
+- CI/CD pipelines for testing MCP tool functionality
+
+## Limitations
+
+- Static data: Library information is baked into the server and may become outdated
+- No actual Zig compilation: The server generates example code but doesn't compile it
+- No audio processing: This is a knowledge/reference server, not an audio processor
+
+## For Further Reading
+
+- [MCP Protocol Documentation](https://modelcontextprotocol.io)
+- [Zig Programming Language](https://ziglang.org)
+- Individual library repositories listed in server responses

package/GEMINI.md

@@ -0,0 +1,266 @@
+# Zig-Audio MCP Server | Project Context and Instructions
+
+## Project Goal
+
+Build an MCP (Model Context Protocol) server that communicates with either local and/or remote resources in order to aid users, **LLMs/Agents**, etc, in writing high-quality `zig` code, with an emphasis in pro-audio/DSP algorithms.
+
+## Project Overview
+
+This is a Node.js/TypeScript project that implements an MCP server to help AI systems assist developers in writing Zig audio and DSP code. The server provides tools for:
+
+- Discovering and learning about Zig audio/DSP libraries
+- Understanding DSP filter algorithms and their implementations
+- Generating starter code for common audio programming tasks
+- Learning fundamental audio/DSP concepts
+- Finding resources for further learning
+
+## Technology Stack
+
+- **Language:** TypeScript
+- **MCP SDK:** @modelcontextprotocol/sdk ^1.0.0
+- **Validation:** Zod ^3.22.4
+- **Runtime:** Node.js 18+
+- **Transport:** Stdio (default), supports Streamable HTTP
+
+## Project Structure
+
+```
+MCP_Zig/
+├── src/
+│   ├── index.ts          # Main MCP server implementation
+│   └── test.ts           # Evaluation tests
+├── dist/                 # Compiled JavaScript
+├── package.json          # Dependencies and scripts
+├── tsconfig.json         # TypeScript configuration
+├── README.md             # Project documentation
+├── AGENTS.md             # This file
+├── evaluation.xml        # Evaluation Q&A pairs
+└── GEMINI.md             # AI/LLM context
+```
+
+## Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm install` | Install dependencies |
+| `npm run build` | Compile TypeScript to JavaScript |
+| `npm start` | Run the MCP server |
+| `npm run dev` | Run in development mode with auto-reload |
+| `npx tsx src/test.ts` | Run evaluation tests |
+
+## MCP Tools
+
+The server exposes 6 tools for AI assistants:
+
+### 1. zig_audio_list_libraries
+List available Zig audio/DSP libraries with optional filtering.
+
+### 2. zig_audio_library_info
+Get detailed information about a specific library (zang, zaudio, bonk, pcm, zig-liquid-dsp, dalek).
+
+### 3. zig_dsp_explain_filter
+Explain DSP filter types (lowpass, highpass, bandpass, notch, biquad, one-pole) with formulas and use cases.
+
+### 4. zig_audio_generate_code
+Generate starter code for audio/DSP tasks (oscillator, envelope, filter, delay, mixer, player, recorder, file operations).
+
+### 5. zig_audio_list_resources
+List learning resources (tutorials, references, examples, articles).
+
+### 6. zig_dsp_get_concepts
+Get explanations of fundamental audio/DSP concepts.
+
+## Development Guidelines
+
+### MCP Protocol Compliance
+- Use `@modelcontextprotocol/sdk` for server implementation
+- Implement proper JSON-RPC 2.0 message handling
+- Use StdioServerTransport for local execution
+- Support Streamable HTTP for remote deployment
+
+### Code Quality
+- All inputs validated with Zod schemas
+- Clear tool names following `zig_audio_*` or `zig_dsp_*` convention
+- Comprehensive tool descriptions with parameter documentation
+- Proper error handling with actionable messages
+
+### Testing
+- Run evaluation tests before submitting changes
+- Ensure all tests pass: `npx tsx src/test.ts`
+- Verify build succeeds: `npm run build`
+
+## Extending the Server
+
+To add new tools:
+
+1. Define Zod input schema in the tool handler section
+2. Add tool definition in the ListToolsRequestSchema handler
+3. Implement the tool logic
+4. Add corresponding test cases
+
+## Zig Audio Ecosystem
+
+The server maintains knowledge of the Zig audio ecosystem:
+
+### Libraries
+- **zang** - Synthesis library (MIT)
+- **zaudio** - miniaudio wrapper (MIT)
+- **bonk** - DSP objects (MPL-2.0)
+- **pcm** - File I/O (MIT)
+- **zig-liquid-dsp** - SDR library (MIT)
+- **dalek** - Experimental engine (MIT)
+
+### Filter Types
+- Low pass, high pass, band pass, notch
+- Biquad, one-pole filters
+
+### Concepts
+- Sample rate, bit depth, buffer size
+- Nyquist frequency, aliasing
+
+## CI/CD and Deployment
+
+The project is designed to be deployed as:
+
+1. **Local tool** - Run via stdio transport
+2. **HTTP service** - Deploy with Streamable HTTP transport
+3. **Docker container** - Containerize for cloud deployment
+
+## Contact and Support
+
+For issues, feature requests, or contributions, please refer to the project repository.
+
+
+# GEMINI.md - AI/LLM Context for MCP Zig Audio
+
+## Project Purpose
+
+This MCP server helps AI assistants provide better assistance for writing Zig code related to audio programming and digital signal processing (DSP).
+
+## What This Server Does
+
+When an AI assistant needs to help with Zig audio/DSP programming, it can call this MCP server to:
+
+1. **Discover Libraries** - Find which Zig libraries are available for specific audio tasks
+2. **Explain Filters** - Understand how different DSP filters work mathematically
+3. **Generate Code** - Create starter implementations for common patterns
+4. **Learn Concepts** - Understand fundamental audio terminology
+5. **Find Resources** - Locate tutorials and documentation
+
+## Tool Usage Examples
+
+### Finding the Right Library
+
+**User Question:** "I want to build a synthesizer in Zig without any dynamic memory allocation. Which library should I use?"
+
+**AI Action:** Call `zig_audio_list_libraries` with feature filter or `zig_audio_library_info` for specific libraries.
+
+**Response:** The server returns information about zang, which is specifically designed for zero-allocation synthesis.
+
+### Understanding DSP Concepts
+
+**User Question:** "What is the Nyquist frequency and why does it matter for audio?"
+
+**AI Action:** Call `zig_dsp_get_concepts` to get explanations.
+
+**Response:** The server returns detailed explanations of Nyquist frequency, sample rate, aliasing, and their relationships.
+
+### Generating Code
+
+**User Question:** "Help me write a simple oscillator in Zig"
+
+**AI Action:** Call `zig_audio_generate_code` with `task: "oscillator"`
+
+**Response:** The server returns starter Zig code for implementing an oscillator.
+
+### Filter Selection
+
+**User Question:** "I need to remove DC offset from an audio signal, which filter should I use?"
+
+**AI Action:** Call `zig_dsp_explain_filter` with different filter types to find the right one.
+
+**Response:** High-pass filter or one-pole filter are suitable for DC offset removal, with explanations and formulas.
+
+## Key Information for AI Assistants
+
+### Library Selection Guide
+
+| Task | Recommended Library |
+|------|-------------------|
+| Synthesis without allocations | zang |
+| Audio playback/recording | zaudio |
+| DSP filters and delay lines | bonk |
+| File I/O (WAV/AIFF) | pcm |
+| Software-defined radio | zig-liquid-dsp |
+| High-performance audio engine | dalek |
+
+### Filter Selection Guide
+
+| Goal | Filter Type |
+|------|-------------|
+| Remove high frequencies | Low Pass |
+| Remove low frequencies (DC offset) | High Pass |
+| Isolate frequency band | Band Pass |
+| Remove specific frequency (hum) | Notch |
+| General EQ/tone control | Biquad |
+| Simple smoothing | One-Pole |
+
+### Code Generation Tasks
+
+The server can generate starter code for:
+- `oscillator` - Sine, square, saw, triangle waves
+- `envelope` - ADSR envelope implementation
+- `filter` - Biquad filter implementation
+- `delay` - Delay line with feedback
+- `mixer` - Multi-channel audio mixer
+- `player` - Audio playback using zaudio
+- `recorder` - Audio recording using zaudio
+- `file-write` - Write audio to WAV file
+- `file-read` - Read audio from WAV file
+
+## Important Notes for AI Assistants
+
+1. **Zig Specifics**: Zig is a systems programming language with manual memory management. The server's library information reflects this (e.g., zang's no-allocation design).
+
+2. **Version Awareness**: The Zig audio ecosystem is actively developing. Library versions and features may change.
+
+3. **License Considerations**: Some libraries have different licenses (MIT vs MPL-2.0). This is included in library information.
+
+4. **Transport Options**: The server runs on stdio by default but can be configured for HTTP transport for remote deployment.
+
+## Error Handling
+
+When tools return errors, they provide actionable messages. Common issues:
+- Invalid library name (check enum values)
+- Missing required parameters
+- Invalid filter type
+
+## Testing the Server
+
+Before relying on this server for production tasks, AI assistants should verify functionality using the test suite:
+
+```bash
+npx tsx src/test.ts
+```
+
+This runs 9 tests covering all tool functionality.
+
+## Integration Points
+
+This MCP server is designed to work with:
+- Claude Desktop
+- Other MCP clients
+- Custom AI assistants
+- CI/CD pipelines for testing MCP tool functionality
+
+## Limitations
+
+- Static data: Library information is baked into the server and may become outdated
+- No actual Zig compilation: The server generates example code but doesn't compile it
+- No audio processing: This is a knowledge/reference server, not an audio processor
+
+## For Further Reading
+
+- [MCP Protocol Documentation](https://modelcontextprotocol.io)
+- [Zig Programming Language](https://ziglang.org)
+- Individual library repositories listed in server responses