audio-mcp 0.1.0

package/dist/paths.js

@@ -0,0 +1,36 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+/** Expand a leading `~` in a path to the user's home directory. */
+export function expandHome(p) {
+    if (p.startsWith("~/") || p === "~") {
+        return join(homedir(), p.slice(1));
+    }
+    return p;
+}
+/**
+ * Resolve audio-mcp storage paths. By default rooted at `~/.audio-mcp`.
+ * A custom root can be supplied (used by tests to isolate storage in a tmp dir).
+ */
+export function resolvePaths(root, sessionsDirOverride) {
+    const rootDir = root ?? join(homedir(), ".audio-mcp");
+    const sessionsDir = sessionsDirOverride
+        ? expandHome(sessionsDirOverride)
+        : join(rootDir, "sessions");
+    return {
+        root: rootDir,
+        sessionsDir,
+        configFile: join(rootDir, "config.json"),
+        logFile: join(rootDir, "audio-mcp.log"),
+    };
+}
+/** Ensure the root and sessions directories exist. Idempotent. */
+export function ensureDirs(paths) {
+    if (!existsSync(paths.root)) {
+        mkdirSync(paths.root, { recursive: true });
+    }
+    if (!existsSync(paths.sessionsDir)) {
+        mkdirSync(paths.sessionsDir, { recursive: true });
+    }
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAShD,mEAAmE;AACnE,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,mBAA4B;IACtE,MAAM,OAAO,GAAG,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,mBAAmB;QACrC,CAAC,CAAC,UAAU,CAAC,mBAAmB,CAAC;QACjC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC9B,OAAO;QACL,IAAI,EAAE,OAAO;QACb,WAAW;QACX,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC;QACxC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC;KACxC,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QACnC,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function startServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,112 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolvePaths, ensureDirs } from "./paths.js";
+import { loadOrCreateConfig } from "./config.js";
+import { createFileLogger } from "./logger.js";
+import { SessionStore } from "./session/store.js";
+import { SessionManager } from "./session/manager.js";
+import { HelperProcessCapture } from "./audio/helper-capture.js";
+import { listInputDevices, resolveMicDevice } from "./audio/devices.js";
+import { buildTools } from "./tools/index.js";
+import { AudioMcpError } from "./errors.js";
+const PKG_VERSION = "0.1.0";
+function toCallToolResult(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        structuredContent: value,
+    };
+}
+function toCallToolError(err) {
+    if (err instanceof AudioMcpError) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: { code: err.code, message: err.message } }, null, 2),
+                },
+            ],
+            structuredContent: { error: { code: err.code, message: err.message } },
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: { code: "INTERNAL_ERROR", message } }, null, 2),
+            },
+        ],
+        structuredContent: { error: { code: "INTERNAL_ERROR", message } },
+    };
+}
+export async function startServer() {
+    const paths = resolvePaths();
+    ensureDirs(paths);
+    const cfg = loadOrCreateConfig(paths);
+    // If the user overrode sessions_dir in config, re-resolve + ensure.
+    const resolved = resolvePaths(undefined, cfg.sessions_dir ?? undefined);
+    ensureDirs(resolved);
+    const logger = createFileLogger(resolved.logFile);
+    logger.info("audio-mcp starting", { version: PKG_VERSION });
+    const store = new SessionStore(resolved.sessionsDir);
+    const manager = new SessionManager({
+        sampleRate: cfg.sample_rate,
+        sessionsDir: resolved.sessionsDir,
+        defaultSource: cfg.default_source,
+        defaultCaptureMode: cfg.default_capture_mode,
+    }, store, () => new HelperProcessCapture(), (src) => resolveMicDevice(src), logger);
+    const tools = buildTools({
+        manager,
+        store,
+        listInputDevices,
+    });
+    const server = new McpServer({ name: "audio-mcp", version: PKG_VERSION });
+    for (const tool of tools) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const callback = async (args) => {
+            try {
+                const result = await tool.handler(args ?? {});
+                return toCallToolResult(result);
+            }
+            catch (err) {
+                logger.error(`tool ${tool.name} failed`, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return toCallToolError(err);
+            }
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.inputSchema }, callback);
+    }
+    const transport = new StdioServerTransport();
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info(`received ${signal}, shutting down`);
+        try {
+            await manager.gracefulStop();
+        }
+        catch (err) {
+            logger.error("shutdown error", { error: err.message });
+        }
+        try {
+            await server.close();
+        }
+        catch {
+            /* ignore */
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    // MCP clients signal shutdown by closing the stdio pipe.
+    process.stdin.on("end", () => void shutdown("stdin-closed"));
+    process.stdin.on("close", () => void shutdown("stdin-closed"));
+    await server.connect(transport);
+    logger.info("audio-mcp listening on stdio");
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/session/manager.d.ts

@@ -0,0 +1,58 @@
+import type { CaptureDevice, CaptureMode } from "../audio/capture.js";
+import type { Logger } from "../logger.js";
+import type { SessionStore } from "./store.js";
+export interface StartSessionInput {
+    label?: string;
+    source?: string;
+    capture?: CaptureMode;
+}
+export interface StartSessionResult {
+    session_id: string;
+    label: string;
+    source: string;
+    capture_mode: CaptureMode;
+    started_at: string;
+    sample_rate: number;
+    channels: number;
+    format: "wav";
+}
+export interface StopSessionResult {
+    session_id: string;
+    label: string;
+    started_at: string;
+    stopped_at: string;
+    duration_seconds: number;
+    file_size_bytes: number;
+    path: string;
+}
+export interface SessionManagerConfig {
+    sampleRate: number;
+    sessionsDir: string;
+    defaultSource: string | null;
+    defaultCaptureMode: CaptureMode;
+}
+export type DeviceResolver = (source?: string | null) => Promise<{
+    deviceId: string | undefined;
+    deviceName: string;
+}>;
+export type CaptureFactory = () => CaptureDevice;
+/**
+ * Owns the single-active-session invariant. Coordinates a CaptureDevice
+ * with a WavWriter and the SessionStore. Per-session `capture` mode
+ * determines the channel layout (1 for mic/system, 2 for both → L=mic R=system).
+ */
+export declare class SessionManager {
+    private readonly cfg;
+    private readonly store;
+    private readonly captureFactory;
+    private readonly resolveDevice;
+    private readonly logger;
+    private active;
+    constructor(cfg: SessionManagerConfig, store: SessionStore, captureFactory: CaptureFactory, resolveDevice: DeviceResolver, logger: Logger);
+    get hasActiveSession(): boolean;
+    get activeSessionId(): string | null;
+    start(input: StartSessionInput): Promise<StartSessionResult>;
+    stop(sessionId: string): Promise<StopSessionResult>;
+    /** Stop the active session on shutdown, swallowing any errors. */
+    gracefulStop(): Promise<void>;
+}

package/dist/session/manager.js

@@ -0,0 +1,184 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { statSync, existsSync } from "node:fs";
+import { WavWriter } from "../audio/wav.js";
+import { AudioMcpError } from "../errors.js";
+const CHANNELS_BY_MODE = {
+    mic: 1,
+    system: 1,
+    both: 2,
+};
+/**
+ * Owns the single-active-session invariant. Coordinates a CaptureDevice
+ * with a WavWriter and the SessionStore. Per-session `capture` mode
+ * determines the channel layout (1 for mic/system, 2 for both → L=mic R=system).
+ */
+export class SessionManager {
+    cfg;
+    store;
+    captureFactory;
+    resolveDevice;
+    logger;
+    active = null;
+    constructor(cfg, store, captureFactory, resolveDevice, logger) {
+        this.cfg = cfg;
+        this.store = store;
+        this.captureFactory = captureFactory;
+        this.resolveDevice = resolveDevice;
+        this.logger = logger;
+    }
+    get hasActiveSession() {
+        return this.active !== null;
+    }
+    get activeSessionId() {
+        return this.active?.meta.session_id ?? null;
+    }
+    async start(input) {
+        if (this.active) {
+            throw new AudioMcpError("SESSION_ALREADY_ACTIVE", `A session is already active (${this.active.meta.session_id}). Stop it before starting a new one.`);
+        }
+        const captureMode = input.capture ?? this.cfg.defaultCaptureMode;
+        const channels = CHANNELS_BY_MODE[captureMode];
+        const sourceInput = input.source ?? this.cfg.defaultSource ?? null;
+        // Mic device is only relevant if we're actually capturing mic.
+        let micDeviceId = undefined;
+        let deviceLabel;
+        if (captureMode === "system") {
+            deviceLabel = "system audio";
+        }
+        else {
+            try {
+                const resolved = await this.resolveDevice(sourceInput);
+                micDeviceId = resolved.deviceId;
+                deviceLabel = resolved.deviceName;
+            }
+            catch (err) {
+                if (err instanceof AudioMcpError)
+                    throw err;
+                throw new AudioMcpError("AUDIO_DEVICE_ERROR", err.message);
+            }
+            if (captureMode === "both")
+                deviceLabel = `${deviceLabel} + system audio`;
+        }
+        const sessionId = randomUUID();
+        const startedAt = new Date().toISOString();
+        const label = input.label?.trim() || `session-${startedAt}`;
+        const wavPath = join(this.cfg.sessionsDir, `${sessionId}.wav`);
+        const capture = this.captureFactory();
+        const writer = new WavWriter(wavPath, {
+            sampleRate: this.cfg.sampleRate,
+            channels,
+        });
+        // Forward PCM chunks straight to the WAV writer. Append errors are logged
+        // but do not abort the session.
+        capture.onData((chunk) => {
+            writer.append(chunk).catch((err) => {
+                this.logger.error("wav append failed", { error: err.message });
+            });
+        });
+        try {
+            await capture.start({
+                sampleRate: this.cfg.sampleRate,
+                channels,
+                captureMode,
+                micDeviceId,
+                excludePid: process.ppid,
+            });
+        }
+        catch (err) {
+            try {
+                await writer.finalize();
+            }
+            catch {
+                /* ignore */
+            }
+            if (err instanceof AudioMcpError)
+                throw err;
+            throw new AudioMcpError("AUDIO_DEVICE_ERROR", err.message);
+        }
+        const meta = {
+            session_id: sessionId,
+            label,
+            source: deviceLabel,
+            capture_mode: captureMode,
+            started_at: startedAt,
+            stopped_at: null,
+            duration_seconds: null,
+            file_size_bytes: null,
+            sample_rate: this.cfg.sampleRate,
+            channels,
+            format: "wav",
+            path: wavPath,
+            is_active: true,
+        };
+        this.store.upsert(meta);
+        this.active = { meta, capture, writer };
+        this.logger.info("session started", {
+            session_id: sessionId,
+            capture_mode: captureMode,
+            source: deviceLabel,
+            label,
+        });
+        return {
+            session_id: sessionId,
+            label,
+            source: deviceLabel,
+            capture_mode: captureMode,
+            started_at: startedAt,
+            sample_rate: this.cfg.sampleRate,
+            channels,
+            format: "wav",
+        };
+    }
+    async stop(sessionId) {
+        if (!this.active || this.active.meta.session_id !== sessionId) {
+            const existing = this.store.get(sessionId);
+            if (!existing) {
+                throw new AudioMcpError("SESSION_NOT_FOUND", `Session not found: ${sessionId}`);
+            }
+            if (!existing.is_active) {
+                throw new AudioMcpError("SESSION_NOT_FOUND", `Session ${sessionId} is not currently active.`);
+            }
+            throw new AudioMcpError("SESSION_NOT_FOUND", `Session ${sessionId} not active in-process.`);
+        }
+        const { meta, capture, writer } = this.active;
+        await capture.stop();
+        const { bytesWritten, durationSeconds } = await writer.finalize();
+        const stoppedAt = new Date().toISOString();
+        const fileSize = existsSync(meta.path) ? statSync(meta.path).size : bytesWritten + 44;
+        const updated = {
+            ...meta,
+            stopped_at: stoppedAt,
+            duration_seconds: durationSeconds,
+            file_size_bytes: fileSize,
+            is_active: false,
+        };
+        this.store.upsert(updated);
+        this.active = null;
+        this.logger.info("session stopped", {
+            session_id: sessionId,
+            duration_seconds: durationSeconds,
+        });
+        return {
+            session_id: sessionId,
+            label: updated.label,
+            started_at: updated.started_at,
+            stopped_at: stoppedAt,
+            duration_seconds: durationSeconds,
+            file_size_bytes: fileSize,
+            path: updated.path,
+        };
+    }
+    /** Stop the active session on shutdown, swallowing any errors. */
+    async gracefulStop() {
+        if (!this.active)
+            return;
+        try {
+            await this.stop(this.active.meta.session_id);
+        }
+        catch (err) {
+            this.logger.error("graceful stop failed", { error: err.message });
+        }
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/session/manager.js.map

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

package/dist/session/store.d.ts

@@ -0,0 +1,35 @@
+import type { CaptureMode } from "../audio/capture.js";
+export interface SessionMetadata {
+    session_id: string;
+    label: string;
+    source: string;
+    capture_mode: CaptureMode;
+    started_at: string;
+    stopped_at: string | null;
+    duration_seconds: number | null;
+    file_size_bytes: number | null;
+    sample_rate: number;
+    channels: number;
+    format: "wav";
+    path: string;
+    is_active: boolean;
+}
+/**
+ * Persists session metadata as `<uuid>.json` alongside the WAV audio file in
+ * the sessions directory. List order is newest-first by `started_at`.
+ */
+export declare class SessionStore {
+    private readonly sessionsDir;
+    constructor(sessionsDir: string);
+    private metaPath;
+    upsert(meta: SessionMetadata): void;
+    get(sessionId: string): SessionMetadata | null;
+    list(): SessionMetadata[];
+    /**
+     * Delete a session's metadata and audio file. Refuses to delete an active
+     * session; throws `SESSION_NOT_FOUND` if the session does not exist.
+     */
+    delete(sessionId: string): void;
+    /** Read current file size from disk if the WAV exists. */
+    currentFileSize(meta: SessionMetadata): number | null;
+}

package/dist/session/store.js

@@ -0,0 +1,72 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync, statSync, } from "node:fs";
+import { join } from "node:path";
+import { AudioMcpError } from "../errors.js";
+/**
+ * Persists session metadata as `<uuid>.json` alongside the WAV audio file in
+ * the sessions directory. List order is newest-first by `started_at`.
+ */
+export class SessionStore {
+    sessionsDir;
+    constructor(sessionsDir) {
+        this.sessionsDir = sessionsDir;
+    }
+    metaPath(sessionId) {
+        return join(this.sessionsDir, `${sessionId}.json`);
+    }
+    upsert(meta) {
+        writeFileSync(this.metaPath(meta.session_id), JSON.stringify(meta, null, 2) + "\n", "utf8");
+    }
+    get(sessionId) {
+        const path = this.metaPath(sessionId);
+        if (!existsSync(path))
+            return null;
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    list() {
+        if (!existsSync(this.sessionsDir))
+            return [];
+        const entries = readdirSync(this.sessionsDir).filter((f) => f.endsWith(".json"));
+        const out = [];
+        for (const entry of entries) {
+            try {
+                const meta = JSON.parse(readFileSync(join(this.sessionsDir, entry), "utf8"));
+                out.push(meta);
+            }
+            catch {
+                // Skip malformed metadata silently.
+            }
+        }
+        out.sort((a, b) => (b.started_at < a.started_at ? -1 : b.started_at > a.started_at ? 1 : 0));
+        return out;
+    }
+    /**
+     * Delete a session's metadata and audio file. Refuses to delete an active
+     * session; throws `SESSION_NOT_FOUND` if the session does not exist.
+     */
+    delete(sessionId) {
+        const meta = this.get(sessionId);
+        if (!meta) {
+            throw new AudioMcpError("SESSION_NOT_FOUND", `Session not found: ${sessionId}`);
+        }
+        if (meta.is_active) {
+            throw new AudioMcpError("SESSION_STILL_ACTIVE", `Session ${sessionId} is still active — stop it before deleting.`);
+        }
+        if (existsSync(meta.path))
+            unlinkSync(meta.path);
+        const metaFile = this.metaPath(sessionId);
+        if (existsSync(metaFile))
+            unlinkSync(metaFile);
+    }
+    /** Read current file size from disk if the WAV exists. */
+    currentFileSize(meta) {
+        if (!existsSync(meta.path))
+            return null;
+        return statSync(meta.path).size;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/session/store.js.map

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

package/dist/tools/index.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { SessionManager } from "../session/manager.js";
+import type { SessionStore } from "../session/store.js";
+import type { DeviceSummary } from "../audio/capture.js";
+export interface ToolsContext {
+    manager: SessionManager;
+    store: SessionStore;
+    listInputDevices: () => Promise<DeviceSummary[]>;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    handler: (input: any) => Promise<any>;
+}
+export declare function buildTools(ctx: ToolsContext): ToolDefinition[];