@ray0404/zig-audio-mcp 0.1.4 → 0.2.0

package/.kilo/plans/mcp-resources-plan.md

@@ -0,0 +1,174 @@
+# Plan: Add MCP Resources to Zig Audio MCP Server
+
+## Executive Summary
+
+Add 10 MCP resources to expose the server's substantial static reference data as read-only context. Currently, all data is only accessible through tools, requiring LLMs to make tool calls for every lookup. Resources enable direct context inclusion, improving efficiency and UX.
+
+## Assessment of Current State
+
+| Component | Count | Status |
+|-----------|-------|--------|
+| Tools | 14 | ✅ Comprehensive |
+| Prompts | 4 | ✅ Good |
+| **Resources** | **0** | ❌ **Missing** |
+
+## Proposed Resources
+
+### Tier 1: Core Reference Resources (Implement First)
+
+| URI | Name | MIME Type | Content |
+|-----|------|-----------|---------|
+| `zig-audio://libraries` | Zig Audio Libraries | `application/json` | Complete library database (9 libs) |
+| `zig-dsp://filters` | DSP Filter Reference | `application/json` | All filter types with formulas |
+| `zig-dsp://concepts` | Audio/DSP Concepts | `application/json` | Fundamental DSP terminology |
+
+### Tier 2: Code & Project Resources
+
+| URI | Name | MIME Type | Content |
+|-----|------|-----------|---------|
+| `zig-audio://templates/code` | Code Templates | `application/json` | 9 code snippets (oscillator, filter, etc.) |
+| `zig-audio://templates/project` | Project Templates | `application/json` | 5 project skeletons |
+| `zig-audio://resources` | Learning Resources | `application/json` | 21 curated tutorials/articles |
+
+### Tier 3: Troubleshooting Resources
+
+| URI | Name | MIME Type | Content |
+|-----|------|-----------|---------|
+| `zig-audio://troubleshooting` | Troubleshooting Guide | `application/json` | 6 issue types with solutions |
+| `zig-audio://compatibility` | Compatibility Matrix | `application/json` | Library version compatibility |
+
+### Tier 4: Parameterized Templates
+
+| URI Template | Name | Description |
+|--------------|------|-------------|
+| `zig-audio://libraries/{name}` | Library Detail | Individual library info |
+| `zig-dsp://filters/{type}` | Filter Detail | Individual filter explanation |
+
+## Implementation Steps
+
+### Step 1: Add Resource Data Constants
+
+Create unified resource data constants extracted from existing handler functions:
+- `LIBRARY_RESOURCES` - From `ZIG_AUDIO_LIBRARIES`
+- `FILTER_RESOURCES` - From `DSP_FILTERS`
+- `CODE_TEMPLATES` - From `handleGenerateCode`
+- `PROJECT_TEMPLATES` - From `handleProjectTemplate`
+- `TROUBLESHOOTING_GUIDES` - From `handleTroubleshoot`
+- `CONCEPTS` - From `handleGetConcepts`
+- `LEARNING_RESOURCES` - From `handleListResources`
+- `COMPATIBILITY_MATRIX` - From `handleDeprecationCheck`
+
+### Step 2: Update Server Capabilities
+
+Add `resources` capability to the server configuration:
+
+```typescript
+{
+  capabilities: {
+    tools: {},
+    prompts: {},
+    resources: {}  // Add this
+  }
+}
+```
+
+### Step 3: Import MCP Resource Types
+
+Add imports from `@modelcontextprotocol/sdk/types.js`:
+- `ListResourcesRequestSchema`
+- `ReadResourceRequestSchema`
+- `ListResourceTemplatesRequestSchema`
+
+### Step 4: Implement ListResourcesRequestSchema Handler
+
+Return all static resources with:
+- `uri` - Unique resource identifier
+- `name` - Human-readable name
+- `description` - Brief description
+- `mimeType` - `application/json`
+
+### Step 5: Implement ReadResourceRequestSchema Handler
+
+Handle URI-based reads:
+- Parse URI scheme and path
+- Route to appropriate data source
+- Return `contents` array with `text` field
+
+### Step 6: Implement ListResourceTemplatesRequestSchema Handler
+
+Return parameterized templates:
+- `zig-audio://libraries/{name}`
+- `zig-dsp://filters/{type}`
+
+### Step 7: Update Evaluation Tests
+
+Add tests for resource functionality:
+- List resources test
+- Read library resource test
+- Read filter resource test
+- Read concepts resource test
+
+## Resource URI Scheme Design
+
+```
+zig-audio://              # Main namespace
+├── libraries             # All libraries
+│   └── {name}           # Individual library (template)
+├── templates
+│   ├── code             # Code templates
+│   └── project          # Project templates
+├── resources            # Learning resources
+├── troubleshooting      # Troubleshooting guides
+└── compatibility        # Compatibility matrix
+
+zig-dsp://                # DSP-specific namespace
+├── filters              # All filters
+│   └── {type}           # Individual filter (template)
+└── concepts             # DSP concepts
+```
+
+## Content Format
+
+All resources return JSON:
+
+```json
+{
+  "uri": "zig-audio://libraries",
+  "mimeType": "application/json",
+  "text": "{ ... JSON data ... }"
+}
+```
+
+## Files to Modify
+
+1. **`src/index.ts`** - Main implementation file
+   - Add resource data constants
+   - Add resource type imports
+   - Add resource capability
+   - Implement 3 resource request handlers
+   - Add resource templates support
+
+2. **`src/test.ts`** - Test file
+   - Add resource listing tests
+   - Add resource reading tests
+
+## Benefits
+
+| Before (Tools Only) | After (Resources + Tools) |
+|---------------------|---------------------------|
+| Must call tool for each lookup | Resources auto-included as context |
+| One-time data fetch | Persistent reference data |
+| Tool call overhead per query | Direct URI access |
+| No discovery mechanism | List all available resources |
+
+## Testing Plan
+
+1. **Unit Tests**: Verify each resource returns correct data
+2. **Integration Tests**: Test ListResources and ReadResource flows
+3. **Evaluation Tests**: Add 2-3 new test cases for resources
+
+## Backward Compatibility
+
+- All existing tools remain unchanged
+- Resources are additive - no breaking changes
+- Clients that don't support resources continue working

package/AGENTS.md

@@ -6,13 +6,18 @@ Build an MCP (Model Context Protocol) server that communicates with either local
 
 ## 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:
+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 and resources for:
 
-- Discovering and learning about Zig audio/DSP libraries
+- Discovering and learning about Zig audio/DSP libraries (9 libraries total)
 - 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
+- Getting intelligent library recommendations
+- Interactive DSP filter design with coefficient calculation
+- Code verification and project template generation
+- Troubleshooting audio programming issues
+- Direct access to reference data via MCP resources
 
 ## Technology Stack
 
@@ -50,13 +55,15 @@ MCP_Zig/
 
 ## MCP Tools
 
-The server exposes 10 tools for AI assistants:
+The server exposes 14 tools for AI assistants:
+
+### Core Tools (6)
 
 ### 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).
+Get detailed information about a specific library (zang, zaudio, bonk, pcm, zig-liquid-dsp, dalek, zsynth, zig-synth, noize).
 
 ### 3. zig_dsp_explain_filter
 Explain DSP filter types (lowpass, highpass, bandpass, notch, biquad, one-pole) with formulas and use cases.
@@ -70,6 +77,8 @@ List learning resources (tutorials, references, examples, articles).
 ### 6. zig_dsp_get_concepts
 Get explanations of fundamental audio/DSP concepts.
 
+### Advanced Tools (8)
+
 ### 7. zig_audio_recommend_library
 Get intelligent library recommendations based on use case and requirements.
 
@@ -82,6 +91,42 @@ Verify Zig code for syntax issues and missing imports.
 ### 10. zig_audio_project_template
 Generate complete project templates for audio applications.
 
+### 11. zig_audio_compare_libraries
+Compare multiple Zig audio libraries side-by-side.
+
+### 12. zig_audio_troubleshoot
+Debug common audio programming issues and get solutions.
+
+### 13. zig_audio_deprecation_check
+Check if a library is deprecated or needs updates for your Zig version.
+
+### 14. zig_dsp_calculate_delay
+Convert delay values between milliseconds, samples, feet, and meters.
+
+## 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.) |
+
 ## Development Guidelines
 
 ### MCP Protocol Compliance
@@ -114,13 +159,16 @@ To add new tools:
 
 The server maintains knowledge of the Zig audio ecosystem:
 
-### Libraries
+### Libraries (9 total)
 - **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)
+- **zsynth** - FM synthesis library (MIT)
+- **zig-synth** - Sokol audio wrapper (MIT)
+- **noize** - Simple synthesis library (MIT)
 
 ### Filter Types
 - Low pass, high pass, band pass, notch

package/GEMINI.md

@@ -50,13 +50,15 @@ MCP_Zig/
 
 ## MCP Tools
 
-The server exposes 6 tools for AI assistants:
+The server exposes 14 tools for AI assistants:
+
+### Core Tools (6)
 
 ### 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).
+Get detailed information about a specific library (zang, zaudio, bonk, pcm, zig-liquid-dsp, dalek, zsynth, zig-synth, noize).
 
 ### 3. zig_dsp_explain_filter
 Explain DSP filter types (lowpass, highpass, bandpass, notch, biquad, one-pole) with formulas and use cases.
@@ -70,6 +72,56 @@ List learning resources (tutorials, references, examples, articles).
 ### 6. zig_dsp_get_concepts
 Get explanations of fundamental audio/DSP concepts.
 
+### Advanced Tools (8)
+
+### 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.
+
+### 11. zig_audio_compare_libraries
+Compare multiple Zig audio libraries side-by-side.
+
+### 12. zig_audio_troubleshoot
+Debug common audio programming issues and get solutions.
+
+### 13. zig_audio_deprecation_check
+Check if a library is deprecated or needs updates for your Zig version.
+
+### 14. zig_dsp_calculate_delay
+Convert delay values between milliseconds, samples, feet, and meters.
+
+## 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.) |
+
 ## Development Guidelines
 
 ### MCP Protocol Compliance
@@ -102,13 +154,16 @@ To add new tools:
 
 The server maintains knowledge of the Zig audio ecosystem:
 
-### Libraries
+### Libraries (9 total)
 - **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)
+- **zsynth** - FM synthesis library (MIT)
+- **zig-synth** - Sokol audio wrapper (MIT)
+- **noize** - Simple synthesis library (MIT)
 
 ### Filter Types
 - Low pass, high pass, band pass, notch
@@ -146,6 +201,12 @@ When an AI assistant needs to help with Zig audio/DSP programming, it can call t
 3. **Generate Code** - Create starter implementations for common patterns
 4. **Learn Concepts** - Understand fundamental audio terminology
 5. **Find Resources** - Locate tutorials and documentation
+6. **Get Recommendations** - Receive intelligent library suggestions based on use cases
+7. **Design Filters** - Interactive DSP filter design with coefficient calculation
+8. **Verify Code** - Check Zig code for syntax issues and missing imports
+9. **Generate Projects** - Create complete project templates with build files
+10. **Troubleshoot Issues** - Debug common audio programming problems
+11. **Access Resources** - Direct context access to reference data via MCP resources
 
 ## Tool Usage Examples
 
@@ -243,7 +304,7 @@ Before relying on this server for production tasks, AI assistants should verify
 npx tsx src/test.ts
 ```
 
-This runs 9 tests covering all tool functionality.
+This runs 30 tests covering all tool functionality and MCP resource access.
 
 ## Integration Points
 

package/README.md

@@ -4,11 +4,11 @@ A Model Context Protocol (MCP) server that provides AI assistance for writing hi
 
 ## 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.
+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 6 major Zig audio/DSP libraries
+- **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
@@ -16,6 +16,8 @@ MCP Zig Audio is an MCP server that helps LLMs, AI agents, and developers write
 - **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
 
@@ -102,7 +104,7 @@ Lists available Zig audio/DSP libraries with optional filtering by category or f
 Gets detailed information about a specific Zig audio library.
 
 **Parameters:**
-- `library` (required): Library name (zang, zaudio, bonk, pcm, zig-liquid-dsp, dalek)
+- `library` (required): Library name (zang, zaudio, bonk, pcm, zig-liquid-dsp, dalek, zsynth, zig-synth, noize)
 
 **Example:**
 ```json
@@ -238,6 +240,62 @@ Generate complete project templates for different types of audio applications.
 }
 ```
 
+### 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
@@ -276,6 +334,24 @@ Generate complete project templates for different types of audio applications.
 - **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
@@ -398,7 +474,7 @@ 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.
+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:
 
@@ -407,8 +483,8 @@ 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
+- All 30 tests should pass
+- Tests cover tool listing, library discovery, filter explanations, code generation, concept queries, and MCP resource access
 
 ## Use Cases