Merge pull request #23 from decibri/development

fix: misleading load errors, temp file buildup, leaky publish manifest

Author: rossarmstrong

.github/workflows/publish.yml

@@ -116,14 +116,30 @@ jobs:
       - name: Run smoke tests
         run: npm test
 
+      - name: Build the publish package
+        # The package is published from the generated dist/ directory, not
+        # from the repo root: scripts/build-package.js writes a manifest
+        # containing only an explicit allowlist of consumer-facing fields
+        # (no scripts, no devDependencies) and copies the runtime files in.
+        # The source package.json is read, never written.
+        run: node scripts/build-package.js
+
       - name: Verify npm package contents (pre-publish gate)
         # Defense-in-depth: verify npm package contents before any publish.
-        # Runs in both publish and dry-run modes. The forbidden patterns exist
-        # because the maintainer working tree holds gitignored registry
-        # credentials (.mcpregistry_*), a publisher binary (mcp-publisher.exe),
-        # and a local runbook (CLAUDE.local.md); this gate stops them ever
-        # reaching a tarball if .gitignore or the package.json `files` list
-        # slips.
+        # Runs in both publish and dry-run modes, against the generated
+        # dist/ directory that actually gets published. The forbidden
+        # patterns exist because the maintainer working tree holds
+        # gitignored registry credentials (.mcpregistry_*), a publisher
+        # binary (mcp-publisher.exe), and a local runbook (CLAUDE.local.md);
+        # this gate stops them ever reaching a tarball if .gitignore or the
+        # build script slips.
+        #
+        # The manifest checks are the field-level equivalent of the file
+        # checks: the published manifest is generated from an allowlist,
+        # and this gate fails the release if a development-only field
+        # (scripts, devDependencies) appears in it anyway. jq reads
+        # dist/package.json directly because `npm pack --dry-run --json`
+        # reports the file list, not the manifest contents.
         #
         # The shape check is not paranoia. npm 10 emitted an array of packed-
         # package records from `npm pack --dry-run --json`; npm 12 emits an
@@ -138,7 +154,7 @@ jobs:
           set -o pipefail
           FAIL=0
 
-          PACK_JSON=$(npm pack --dry-run --json)
+          PACK_JSON=$(npm pack --dry-run --json ./dist)
           echo "Raw npm pack output:"
           echo "$PACK_JSON"
           echo ""
@@ -165,6 +181,7 @@ jobs:
             package.json \
             index.js \
             lib/audio.js \
+            lib/cleanup.js \
             lib/llm.js \
             lib/transcribe.js \
             lib/validate.js \
@@ -193,6 +210,19 @@ jobs:
             fi
           done
 
+          echo ""
+          echo "Published manifest (dist/package.json) field checks:"
+          for field in scripts devDependencies
+          do
+            if jq -e --arg f "$field" 'has($f)' dist/package.json > /dev/null; then
+              echo "  [FAIL] published manifest must not carry: $field"
+              echo "         got: $(jq -c --arg f "$field" '.[$f]' dist/package.json)"
+              FAIL=1
+            else
+              echo "  [OK]   manifest field absent: $field"
+            fi
+          done
+
           echo ""
           if [ "$FAIL" -ne 0 ]; then
             echo "================================================"
@@ -255,14 +285,23 @@ jobs:
           fi
           echo "OK: npm ${NPM_VERSION} supports trusted publishing"
 
+      - name: Build the publish package
+        # Same generated dist/ the verify job gated: the published manifest
+        # is built from an explicit field allowlist (no scripts, no
+        # devDependencies) and the runtime files are copied in. The build
+        # needs no npm install; scripts/build-package.js uses only node:fs.
+        run: node scripts/build-package.js
+
       # npm Trusted Publishing (OIDC) supplies auth automatically given
       # `id-token: write` and the registered trusted publisher record. No
       # NODE_AUTH_TOKEN is used, and no --provenance flag is passed:
       # provenance is generated automatically from the OIDC token. The
       # publish is gated on either a tag-push trigger or a
-      # workflow_dispatch run with `publish: true`.
+      # workflow_dispatch run with `publish: true`. Published from the
+      # generated dist/ directory (cd, matching the decibri publish
+      # workflows), never from the repo root.
       - name: Publish mcp-listen
-        run: npm publish --access public
+        run: cd dist && npm publish --access public
 
       - name: Create GitHub Release
         if: github.event_name == 'push'

.gitignore

@@ -11,4 +11,7 @@ mcp-publisher.exe
 .mcpregistry_github_token
 .mcpregistry_registry_token
 
-CLAUDE.local.md
+CLAUDE.local.md
+
+# Generated publish package, assembled by scripts/build-package.js
+dist/

CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-14
+
+### Fixed
+
+- A whisper addon that is installed but fails to load (for example, a
+  missing native library) was reported as "not installed", telling the
+  user to run an install command that was already satisfied and could
+  not help. The two failure modes are now distinguished: a genuinely
+  missing package keeps the install guidance, and a load failure
+  reports itself as one and surfaces the underlying loader error, which
+  names the thing the user can actually act on. The optional `ollama`
+  client had the same defect and is fixed the same way.
+- `capture_audio` never removed the WAV files it wrote to the system
+  temporary directory. An agent calling it repeatedly accumulated
+  recordings of the user's microphone there indefinitely.
+
+### Changed
+
+- WAV files written by `capture_audio` to the temporary directory are
+  now removed at server start once they are older than 24 hours. The
+  path returned by a call remains valid for the session and well
+  beyond it. The sweep matches only the exact file names the tool
+  generates, never touches anything else, and cannot fail or delay
+  startup. `voice_query` continues to delete its recording as soon as
+  the query completes.
+- The published package no longer carries a `scripts` block. The
+  package is built from a generated manifest holding an explicit
+  allowlist of consumer-facing fields, so development-only fields
+  cannot reach consumers. `npm test` in an installed copy now reports
+  a missing script instead of failing on a test file that is
+  deliberately not shipped. The pre-publish gate fails the release if
+  the published manifest carries `scripts` or `devDependencies`. The
+  tarball's runtime contents are unchanged.
+- Documentation brought current: the argument validation introduced in
+  0.3.0 is documented, the whisper model section no longer implies the
+  model downloads itself, Known Limitations describes the temp-file
+  retention, a troubleshooting entry covers the addon load-failure
+  message, and the security policy's supported-versions table reflects
+  the 0.3+ line.
+
+### Added
+
+- Deterministic test coverage, on every platform, for paths the smoke
+  suite could not previously reach: the optional-dependency load
+  failures in the transcription and LLM layers (stubbed at the module
+  loader, so no whisper model or Ollama daemon is needed), the
+  temp-directory sweep, and the packed manifest (builds and packs the
+  real tarball, asserts the source manifest is never modified, and
+  asserts an installed copy's `npm test` cannot fail on a module that
+  was never shipped).
+
 ## [0.3.0] - 2026-07-14
 
 ### Changed
@@ -200,7 +251,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   listing, WAV output validation, and error responses.
 - Tag-triggered npm publish workflow.
 
-[Unreleased]: https://github.com/decibri/mcp-listen/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/decibri/mcp-listen/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/decibri/mcp-listen/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/decibri/mcp-listen/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/decibri/mcp-listen/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/decibri/mcp-listen/compare/v0.1.3...v0.2.0

README.md

@@ -91,6 +91,8 @@ Intel Mac (darwin-x64) is not supported: Apple has discontinued the platform and
 
 ## Tool Reference
 
+Arguments are validated before anything is recorded or written. An argument a tool does not declare is rejected with an error naming it, rather than silently ignored. `duration_ms` must be an integer between 100 and 30000; `device` must be a non-negative integer index or a non-empty string id from `list_audio_devices`. A rejected call writes nothing to disk.
+
 ### list_audio_devices
 
 Returns a JSON array of available audio input devices.
@@ -194,9 +196,9 @@ The model is ~150MB and downloads once. You can also set the `WHISPER_MODEL_PATH
 
 1. **Fixed recording duration.** You specify how long to record. There is no "stop when I stop talking" mode yet.
 2. **`voice_query` requires Ollama running.** If Ollama isn't running, the tool returns a clear error message.
-3. **Whisper model downloads on first use.** The first `voice_query` call requires a pre-downloaded model (~150MB).
+3. **Whisper model must be downloaded before first use.** `voice_query` does not download the model itself; the first call requires a pre-downloaded model (~150MB). See [Whisper Model Setup](#whisper-model-setup).
 4. **No streaming.** MCP's request/response pattern means the entire recording is captured, then transcribed, then sent to the LLM. No real-time partial results.
-5. **Temp files.** `capture_audio` writes WAV files to the system temp directory. They are not automatically cleaned up. `voice_query` cleans up after itself.
+5. **Temp files.** `capture_audio` writes WAV files to the system temp directory and returns the path, so the file has to outlive the call for the caller to read it. Recordings older than 24 hours are removed the next time the server starts; recordings made since the last restart persist until then. `voice_query` deletes its recording as soon as the query completes.
 
 ## Troubleshooting
 
@@ -209,6 +211,9 @@ Some Ollama installations start as a background service automatically. If you se
 **Whisper: "model not found"**
 The whisper model file must be downloaded before first use. See [Whisper Model Setup](#whisper-model-setup) for instructions.
 
+**Whisper: "installed but failed to load"**
+The `@kutalia/whisper-node-addon` package is present but a native library it depends on is missing or incompatible on your system. The error includes the underlying loader message naming the library. Reinstalling the package will not help; resolve the named library instead.
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE) for details.

SECURITY.md

@@ -28,7 +28,7 @@ Understanding what the server touches is useful context when assessing the impac
 mcp-listen:
 
 - Reads from audio input devices when a capture tool is invoked
-- Writes WAV files to the system temporary directory. `capture_audio` returns the recording's path to the caller; `voice_query` deletes its recording when the query completes.
+- Writes WAV files to the system temporary directory. `capture_audio` returns the recording's path to the caller; `voice_query` deletes its recording when the query completes. At startup the server removes its own recordings older than 24 hours from the temporary directory, matching only the file names it generates, so `capture_audio` recordings do not accumulate indefinitely.
 - Transcribes captured audio locally, in process, using whisper.cpp. Audio never leaves the machine.
 - Sends transcribed text to the local Ollama daemon at `127.0.0.1:11434` when `voice_query` is used. This is the only network call in the codebase. An Ollama daemon configured with cloud models will relay that text off the machine; that relay is a property of the user's Ollama configuration, not of mcp-listen, but it is worth knowing when assessing where text can travel.
 - Reads the `WHISPER_MODEL_PATH` environment variable to locate the local Whisper model. It reads no API credentials: none are used. The bundled Ollama client library can read `OLLAMA_API_KEY`, but it attaches that credential only to requests to `ollama.com`, and mcp-listen only ever calls the local daemon, so that code path is unreachable.
@@ -55,7 +55,8 @@ mcp-listen is published to npm as a single JavaScript package. It ships no binar
 
 - The package is published exclusively from GitHub Actions on GitHub-hosted runners. Nothing is published manually.
 - Publishing is triggered only by tagged releases and is gated behind a protected GitHub environment requiring manual approval, restricted to `v*` tags.
-- A pre-publish verification gate asserts that every file the package ships is present in the tarball and fails the release if any credential, publisher binary, or test fixture is present.
+- The published package is assembled into a build directory by a generator that copies the runtime files and writes a manifest containing only an explicit allowlist of consumer-facing fields. The development manifest, with its scripts and tooling, is never published.
+- A pre-publish verification gate asserts that every file the package ships is present in the tarball, that no credential, publisher binary, or test fixture is present, and that the published manifest carries no scripts and no development dependencies. It fails the release otherwise.
 - The full build and release configuration is open source and auditable in `.github/workflows/publish.yml`.
 
 ### Publishing and authentication
@@ -79,8 +80,8 @@ This security policy applies to the following versions:
 
 | Version | Supported |
 | --- | --- |
-| 0.2.x | Yes |
-| < 0.2 | No |
+| 0.4.x | Yes |
+| < 0.4 | No |
 
 Security fixes are applied to the latest release only. mcp-listen is pre-1.0 and older versions are not backported. Upgrade to the latest release.
 

index.js

@@ -9,6 +9,7 @@ const { version } = require('./package.json');
 const { listDevices, captureAudio, getActiveMic } = require('./lib/audio');
 const { transcribe } = require('./lib/transcribe');
 const { chat } = require('./lib/llm');
+const { sweepStaleRecordings } = require('./lib/cleanup');
 const {
   validateListDevicesArgs,
   validateCaptureArgs,
@@ -220,6 +221,10 @@ process.on('SIGTERM', shutdown);
 // ── Start ──────────────���────────────────────────────────────
 
 (async () => {
+  // Not awaited: the sweep is best-effort housekeeping and must never
+  // delay or prevent the server coming up.
+  sweepStaleRecordings();
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('mcp-listen server started');

lib/cleanup.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// capture_audio's contract is to return the recording's path, so its WAV
+// cannot be deleted when the call completes; before this sweep existed,
+// those files simply accumulated in the temp directory forever, which is
+// a privacy problem as much as a disk one (they are microphone
+// recordings). The sweep runs once at server start and removes only
+// recordings old enough that no caller can still be using them.
+//
+// The retention window is deliberately generous: a caller is expected to
+// consume the file within its session, and 24 hours outlives any
+// plausible session while still bounding accumulation to one day of
+// recordings between restarts.
+const RETENTION_MS = 24 * 60 * 60 * 1000;
+
+// Exactly the names capture_audio generates: the prefix, a millisecond
+// timestamp, the extension. Anything else in the temp directory, however
+// similar, was not created by this tool and is never touched.
+const RECORDING_NAME = /^mcp-listen-\d+\.wav$/;
+
+// Best-effort by design: an unreadable directory, a locked file, or a
+// file deleted underneath us must neither throw nor stop the sweep. The
+// caller fires this without awaiting it, so server startup never blocks
+// on it. Returns the number of files removed.
+async function sweepStaleRecordings({ dir = os.tmpdir(), maxAgeMs = RETENTION_MS } = {}) {
+  let names;
+  try {
+    names = await fs.promises.readdir(dir);
+  } catch {
+    return 0;
+  }
+
+  const cutoff = Date.now() - maxAgeMs;
+  let removed = 0;
+  for (const name of names) {
+    if (!RECORDING_NAME.test(name)) continue;
+    const filePath = path.join(dir, name);
+    try {
+      const stat = await fs.promises.stat(filePath);
+      if (!stat.isFile() || stat.mtimeMs > cutoff) continue;
+      await fs.promises.unlink(filePath);
+      removed++;
+    } catch {
+      // Locked, already gone, or unreadable: leave it and keep going.
+    }
+  }
+  return removed;
+}
+
+module.exports = { sweepStaleRecordings, RETENTION_MS };

lib/llm.js

@@ -1,10 +1,23 @@
 'use strict';
 
-let Ollama;
+// Optional dependency: a load failure must not stop the server, so it
+// degrades to an error result at call time. The caught error is kept
+// because "not installed" and "installed but failed to load" demand
+// different actions: only a MODULE_NOT_FOUND naming the package itself
+// is fixed by npm install; any other failure needs the underlying error.
+// Same reasoning as the whisper addon handling in lib/transcribe.js.
+let Ollama = null;
+let ollamaLoadError = null;
 try {
   ({ Ollama } = require('ollama'));
-} catch {
-  Ollama = null;
+} catch (err) {
+  ollamaLoadError = err;
+}
+
+function isNotInstalled(err) {
+  return err.code === 'MODULE_NOT_FOUND' &&
+    typeof err.message === 'string' &&
+    err.message.includes("'ollama'");
 }
 
 const REQUEST_TIMEOUT_MS = 60000;
@@ -19,8 +32,15 @@ function isConnectionError(err) {
 
 async function chat({ text, model = 'llama3.2', systemPrompt = 'You are a helpful assistant.', host } = {}) {
   if (!Ollama) {
+    if (ollamaLoadError && !isNotInstalled(ollamaLoadError)) {
+      return {
+        error: `ollama package is installed but failed to load: ${ollamaLoadError.message}.`,
+        cause: ollamaLoadError
+      };
+    }
     return {
-      error: 'ollama package is not installed. Install it with: npm install ollama'
+      error: 'ollama package is not installed. Install it with: npm install ollama',
+      cause: ollamaLoadError
     };
   }