audio-mcp 0.1.0

package/dist/tools/index.js

@@ -0,0 +1,180 @@
+import { z } from "zod";
+import { AudioMcpError } from "../errors.js";
+import { statSync, existsSync } from "node:fs";
+import { sliceWav } from "../audio/wav.js";
+const WAV_HEADER_SIZE = 44;
+const MAX_CHUNK_SECONDS = 300;
+function toSessionListItem(meta) {
+    // For active sessions, report a live snapshot of disk size + duration
+    // so agents can poll progress without stopping the session.
+    let fileSize = meta.file_size_bytes;
+    let durationSeconds = meta.duration_seconds;
+    if (meta.is_active && existsSync(meta.path)) {
+        fileSize = statSync(meta.path).size;
+        const dataBytes = Math.max(0, fileSize - WAV_HEADER_SIZE);
+        const bytesPerSec = meta.sample_rate * meta.channels * 2;
+        durationSeconds = bytesPerSec > 0 ? dataBytes / bytesPerSec : 0;
+    }
+    return {
+        session_id: meta.session_id,
+        label: meta.label,
+        capture_mode: meta.capture_mode,
+        started_at: meta.started_at,
+        stopped_at: meta.stopped_at,
+        duration_seconds: durationSeconds,
+        file_size_bytes: fileSize,
+        channels: meta.channels,
+        is_active: meta.is_active,
+    };
+}
+export function buildTools(ctx) {
+    const startSession = {
+        name: "start_session",
+        description: "Start a new audio capture session. Captures mic, system output, or both into a single WAV. " +
+            "For capture='both' the file is stereo with L=mic and R=system audio. " +
+            "Fails with SESSION_ALREADY_ACTIVE if a session is already running.",
+        inputSchema: {
+            label: z.string().optional().describe("Human-readable name for the session."),
+            source: z
+                .string()
+                .optional()
+                .describe("Microphone device uniqueID or substring-matched name. Only used when capture includes 'mic'. Omit for system default."),
+            capture: z
+                .enum(["mic", "system", "both"])
+                .optional()
+                .describe("What to capture. 'mic'=microphone only; 'system'=system audio output only (requires Screen Recording permission); 'both'=stereo WAV with L=mic R=system. Defaults to 'both'."),
+        },
+        handler: async (input) => {
+            return ctx.manager.start({
+                label: input.label,
+                source: input.source,
+                capture: input.capture,
+            });
+        },
+    };
+    const stopSession = {
+        name: "stop_session",
+        description: "Stop the active capture session and finalize the WAV file.",
+        inputSchema: {
+            session_id: z.string().describe("The UUID returned by start_session."),
+        },
+        handler: async (input) => {
+            return ctx.manager.stop(input.session_id);
+        },
+    };
+    const getAudio = {
+        name: "get_audio",
+        description: "Return a base64-encoded WAV slice of a recorded session. Max 300 seconds per call; " +
+            "chunk larger ranges yourself.",
+        inputSchema: {
+            session_id: z.string(),
+            start_second: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Start of the slice, in seconds (default 0)."),
+            end_second: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("End of the slice, in seconds (default: end of session)."),
+            format: z
+                .enum(["wav", "opus"])
+                .optional()
+                .describe("Output format. Only 'wav' is supported in v1."),
+        },
+        handler: async (input) => {
+            if (input.format && input.format === "opus") {
+                throw new AudioMcpError("NOT_IMPLEMENTED", "Opus output is planned for v2. Request format: 'wav' instead.");
+            }
+            const meta = ctx.store.get(input.session_id);
+            if (!meta) {
+                throw new AudioMcpError("SESSION_NOT_FOUND", `Session not found: ${input.session_id}`);
+            }
+            // Active sessions are readable — we compute the live duration from
+            // the WAV file's current size so agents can poll mid-recording.
+            let sessionDuration;
+            if (meta.is_active && existsSync(meta.path)) {
+                const dataBytes = Math.max(0, statSync(meta.path).size - WAV_HEADER_SIZE);
+                const bytesPerSec = meta.sample_rate * meta.channels * 2;
+                sessionDuration = bytesPerSec > 0 ? dataBytes / bytesPerSec : 0;
+            }
+            else {
+                sessionDuration = meta.duration_seconds ?? 0;
+            }
+            const startSec = input.start_second ?? 0;
+            const endSec = input.end_second ?? sessionDuration;
+            if (endSec <= startSec) {
+                throw new AudioMcpError("INVALID_INPUT", `end_second (${endSec}) must be greater than start_second (${startSec}).`);
+            }
+            if (endSec - startSec > MAX_CHUNK_SECONDS) {
+                throw new AudioMcpError("CHUNK_TOO_LARGE", `Requested ${endSec - startSec}s exceeds the 300s chunk limit. ` +
+                    `Split into multiple calls, e.g. [${startSec}, ${startSec + MAX_CHUNK_SECONDS}] then ` +
+                    `[${startSec + MAX_CHUNK_SECONDS}, ${endSec}].`);
+            }
+            const slice = sliceWav(meta.path, startSec, endSec);
+            return {
+                session_id: input.session_id,
+                start_second: startSec,
+                end_second: slice.endSecond,
+                duration_seconds: slice.durationSeconds,
+                format: "wav",
+                sample_rate: slice.sampleRate,
+                channels: slice.channels,
+                audio_base64: slice.audio.toString("base64"),
+                size_bytes: slice.byteLength,
+            };
+        },
+    };
+    const listSessions = {
+        name: "list_sessions",
+        description: "List all recorded sessions, newest first.",
+        inputSchema: {},
+        handler: async () => {
+            return { sessions: ctx.store.list().map(toSessionListItem) };
+        },
+    };
+    const getSession = {
+        name: "get_session",
+        description: "Return metadata for a single session.",
+        inputSchema: {
+            session_id: z.string(),
+        },
+        handler: async (input) => {
+            const meta = ctx.store.get(input.session_id);
+            if (!meta) {
+                throw new AudioMcpError("SESSION_NOT_FOUND", `Session not found: ${input.session_id}`);
+            }
+            return toSessionListItem(meta);
+        },
+    };
+    const listAudioSources = {
+        name: "list_audio_sources",
+        description: "List available microphone input devices on this machine.",
+        inputSchema: {},
+        handler: async () => {
+            return { sources: await ctx.listInputDevices() };
+        },
+    };
+    const deleteSession = {
+        name: "delete_session",
+        description: "Permanently delete a session's audio file and metadata. Refuses active sessions.",
+        inputSchema: {
+            session_id: z.string(),
+        },
+        handler: async (input) => {
+            ctx.store.delete(input.session_id);
+            return { session_id: input.session_id, deleted: true };
+        },
+    };
+    return [
+        startSession,
+        stopSession,
+        getAudio,
+        listSessions,
+        getSession,
+        listAudioSources,
+        deleteSession,
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "audio-mcp",
+  "version": "0.1.0",
+  "description": "Local MCP server for macOS that captures microphone + system audio into explicit sessions and exposes raw WAV audio (stereo L=mic, R=system) to AI agents.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "audio-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "dist/bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js && npm run build:helper",
+    "build:ts": "tsc && chmod +x dist/index.js",
+    "build:helper": "./scripts/build-helper.sh",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:swift": "cd swift-helper && swift test",
+    "test:watch": "vitest",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'",
+    "prepublishOnly": "npm run build && npm test && lipo -info dist/bin/audio-capture-helper"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "audio",
+    "recording",
+    "macos",
+    "claude",
+    "cursor"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "wavefile": "^11.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "@typescript-eslint/eslint-plugin": "^7.16.0",
+    "@typescript-eslint/parser": "^7.16.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.2",
+    "typescript": "^5.5.3",
+    "vitest": "^1.6.0"
+  }
+}