Merge pull request #19 from decibri/development

feat: upgrade decibri to 5.0.0, select devices by stable id

Author: rossarmstrong

.github/workflows/ci.yml

@@ -63,13 +63,13 @@ jobs:
         shell: bash
         run: |
           node -e '
-            const Decibri = require("decibri");
+            const { Microphone } = require("decibri");
             try {
-              const devices = Decibri.devices();
-              console.log("Decibri.devices() returned:");
+              const devices = Microphone.devices();
+              console.log("Microphone.devices() returned:");
               console.log(JSON.stringify(devices, null, 2));
             } catch (err) {
-              console.log("Decibri.devices() threw:");
+              console.log("Microphone.devices() threw:");
               console.log(err && err.stack ? err.stack : String(err));
             }
           '

.github/workflows/publish.yml

@@ -105,9 +105,9 @@ jobs:
           echo "OK: npm ${NPM_VERSION} supports trusted publishing"
 
       - name: Install ALSA runtime (Linux)
-        # decibri's native addon links ALSA on Linux. Harmless today at decibri
-        # 1.x; required once decibri 5.x lands. Mirrors the platform setup in the
-        # decibri repo's own build matrix.
+        # decibri's native addon links ALSA on Linux. Required since decibri
+        # 5.x. Mirrors the platform setup in the decibri repo's own build
+        # matrix.
         run: sudo apt-get update && sudo apt-get install -y libasound2-dev
 
       - name: Install dependencies

CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-13
+
+### Changed
+
+- **Breaking: device indexes are renumbered.** Device enumeration comes from
+  the new capture engine, so the indexes and names reported by
+  `list_audio_devices` differ from 0.1.x: indexes are renumbered from a
+  different base, Windows loopback endpoints are no longer listed, and
+  device names use the shorter WASAPI form. A hardcoded `device` index
+  recorded under 0.1.x will silently select a different microphone, or fail
+  if it is now out of range. Re-run `list_audio_devices` after upgrading and
+  switch to the stable `id`, which does not shift.
+- Upgraded decibri from 1.0.0 to 5.0.0. The capture engine is now Rust
+  (cpal) rather than C++ (PortAudio), shipped as prebuilt per-platform
+  binaries with no install script and no source-build fallback.
+- A microphone whose native rate differs from the requested 16 kHz is now
+  resampled inside the capture engine, so recordings are delivered at the
+  configured rate on every device.
+- npm publishing now uses trusted publishing (OIDC) with provenance and a
+  manual approval gate. No npm token is involved.
+
+### Added
+
+- Each device returned by `list_audio_devices` now includes a stable `id`
+  string alongside `index`, `name`, `maxInputChannels`, `defaultSampleRate`,
+  and `isDefault`. The `id` survives reboots and device changes; `index` is
+  positional and `name` is not unique. Rarely, a device the host cannot
+  identify reports an empty `id` and remains selectable by index.
+- The `device` parameter of `capture_audio` and `voice_query` accepts the
+  stable device `id` (string) as well as the numeric index. Existing callers
+  passing a number are unchanged.
+- On platforms decibri publishes no binary for, mcp-listen now fails at
+  startup with a message naming the platform and listing the supported set,
+  instead of surfacing the module loader's generic error.
+- A capture on the default-device path now fails with an actionable error
+  when the system has no usable default input device: if no enumerated
+  device is flagged default and the capture fails, the error reports the
+  device count and points at `list_audio_devices`, with the original error
+  included; if the only input device is the ALSA null device (the state of
+  headless Linux hosts), the default path refuses rather than recording
+  silence. Selecting a device explicitly, including the null device, is
+  unaffected.
+- Cross-platform CI: the smoke tests run on Linux, Windows, and macOS across
+  Node.js 18, 20, and 22 on every push and pull request.
+
+### Removed
+
+- Intel Mac (darwin-x64) support. Apple has discontinued the platform and no
+  decibri 5.x binary is published for it. decibri 1.x could fall back to
+  compiling from source at install time; 5.x ships prebuilt binaries only,
+  so the fallback that made Intel Mac work is gone.
+
+### Fixed
+
+- `capture_audio` delivers exactly the requested duration of audio. Capture
+  now stops once the requested amount of PCM has arrived rather than on a
+  wall-clock timer, so stream startup time is no longer silently deducted
+  from the recording and the WAV payload is byte-exact.
+
+## [0.1.3] - 2026-04-16
+
+### Changed
+
+- Updated project metadata after the repository transfer to the decibri
+  organization: `mcpName` is now `io.github.decibri/mcp-listen`, and the
+  author, repository, homepage, and README links point at decibri.
+
+### Fixed
+
+- LICENSE copyright holder corrected to Decibri.
+
+## [0.1.2] - 2026-04-09
+
+### Added
+
+- `server.json` manifest for MCP Registry publication.
+
+### Changed
+
+- README description revised; decibri links updated from decibri.dev to
+  decibri.com.
+
+## [0.1.1] - 2026-04-06
+
+### Added
+
+- `mcpName` field in `package.json` for MCP Registry ownership verification.
+
+## [0.1.0] - 2026-04-05
+
+### Added
+
+- Initial release: a stdio MCP server giving MCP-compatible agents access to
+  the microphone.
+- `list_audio_devices` tool: enumerate available audio input devices.
+- `capture_audio` tool: record from the microphone for a requested duration
+  (100 to 30000 ms) and save as WAV, with duration validation, concurrent
+  capture protection, and safety timeouts.
+- `voice_query` tool: capture, transcribe with whisper.cpp, and query a local
+  Ollama LLM. Whisper and Ollama are optional dependencies; the capture tools
+  work without them.
+- Smoke test suite covering server initialization, tool advertising, device
+  listing, WAV output validation, and error responses.
+- Tag-triggered npm publish workflow.
+
+[Unreleased]: https://github.com/decibri/mcp-listen/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/decibri/mcp-listen/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/decibri/mcp-listen/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/decibri/mcp-listen/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/decibri/mcp-listen/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/decibri/mcp-listen/releases/tag/v0.1.0

README.md

@@ -71,6 +71,14 @@ npm install -g mcp-listen
 
 ## Requirements
 
+**Supported platforms:**
+
+- Windows x64
+- macOS Apple silicon (arm64)
+- Linux x64 and arm64 (glibc)
+
+Intel Mac (darwin-x64) is not supported: Apple has discontinued the platform and no decibri binary is published for it.
+
 **For `list_audio_devices` and `capture_audio`:**
 
 - Node.js 18+
@@ -93,11 +101,13 @@ Returns a JSON array of available audio input devices.
 
 ```json
 [
-  { "index": 3, "name": "Microphone (Creative Live! Cam)", "isDefault": true, "maxInputChannels": 2, "defaultSampleRate": 48000 },
-  { "index": 4, "name": "Microphone Array (Intel)", "isDefault": false, "maxInputChannels": 2, "defaultSampleRate": 48000 }
+  { "index": 0, "name": "Microphone", "id": "wasapi:{0.0.1.00000000}.{6b187949-26ea-470b-907d-66bf87261530}", "maxInputChannels": 2, "defaultSampleRate": 48000, "isDefault": true },
+  { "index": 1, "name": "Microphone Array", "id": "wasapi:{0.0.1.00000000}.{b7a6e3e2-a62b-4e92-9320-947c4be98552}", "maxInputChannels": 2, "defaultSampleRate": 48000, "isDefault": false }
 ]
 ```
 
+The `id` is stable across reboots and device changes. The `index` is positional and can shift when devices are added or removed, and names are not unique. Prefer `id` when selecting a device. In the rare case the host cannot produce a stable id for a device, its `id` is an empty string and it can only be selected by `index`.
+
 ### capture_audio
 
 Records audio from the microphone and saves as a WAV file.
@@ -107,7 +117,7 @@ Records audio from the microphone and saves as a WAV file.
 | Parameter | Type | Default | Description |
 | ---------- | ------ | --------- | ------------- |
 | `duration_ms` | number | 5000 | Recording duration in milliseconds (100-30000) |
-| `device` | number | system default | Device index from `list_audio_devices` |
+| `device` | number or string | system default | Device index or stable device `id` from `list_audio_devices` |
 
 **Example response:**
 
@@ -130,7 +140,7 @@ Full voice pipeline: capture audio, transcribe with whisper.cpp, send to Ollama,
 | Parameter | Type | Default | Description |
 | ----------- | ------ | --------- | ------------- |
 | `duration_ms` | number | 5000 | Recording duration in milliseconds (100-30000) |
-| `device` | number | system default | Device index from `list_audio_devices` |
+| `device` | number or string | system default | Device index or stable device `id` from `list_audio_devices` |
 | `whisper_model` | string | ggml-base.en.bin | Path or filename of Whisper GGML model |
 | `language` | string | en | Language code for transcription |
 | `model` | string | llama3.2 | Ollama model name |

assets/.gitkeep

@@ -23,7 +23,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: 'list_audio_devices',
-      description: 'List available audio input devices (microphones) on this machine.',
+      description: 'List available audio input devices (microphones) on this machine. Each device has a numeric index, a human-readable name, and a stable id. Prefer the id when selecting a device: indexes can shift when devices are added or removed, and names are not unique.',
       inputSchema: { type: 'object', properties: {} }
     },
     {
@@ -37,8 +37,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: 'Recording duration in milliseconds, 100-30000 (default: 5000)'
           },
           device: {
-            type: 'number',
-            description: 'Device index from list_audio_devices. Omit for system default microphone.'
+            type: ['number', 'string'],
+            description: 'Device to record from: the numeric index or the stable string id, both reported by list_audio_devices. Prefer the id; indexes can shift when devices are added or removed. Omit for system default microphone.'
           }
         }
       }
@@ -54,8 +54,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: 'Recording duration in milliseconds, 100-30000 (default: 5000)'
           },
           device: {
-            type: 'number',
-            description: 'Device index from list_audio_devices. Omit for system default microphone.'
+            type: ['number', 'string'],
+            description: 'Device to record from: the numeric index or the stable string id, both reported by list_audio_devices. Prefer the id; indexes can shift when devices are added or removed. Omit for system default microphone.'
           },
           whisper_model: {
             type: 'string',