@open-recording/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @open-recording/mcp
+
+MCP server for [open-recording](https://github.com/simonliu-ai-product/open-recording) — lets any agent framework press record, stop, transcribe, and read the transcript back.
+
+Mounted on the dev server by `open-recording dev --mcp`. It has to run in that process: the recorder state machine lives there, and the tools reach the browser studio through its open event stream.
+
+```bash
+pnpm add -D @open-recording/mcp
+```
+
+See the [repo README](https://github.com/simonliu-ai-product/open-recording#readme) for the tool list.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { OpenRecordingConfig } from "@open-recording/core";
+//#region src/index.d.ts
+type OpenRecordingMcpOptions = {
+  /** The workspace root — the directory holding `recordings/`. */
+  userCwd: string;
+  version?: string;
+  config?: OpenRecordingConfig;
+  /**
+   * Extra hostnames allowed in Host/Origin headers. Loopback is always allowed;
+   * add to this only when the endpoint is deliberately exposed.
+   */
+  allowedHosts?: string[];
+};
+/**
+ * A fresh server per request. The recorder state it acts on is not held here —
+ * it lives in the dev server process this endpoint is mounted on — so there is
+ * nothing worth carrying between calls, which is the stateless shape that lets
+ * any client connect without a session handshake.
+ */
+declare function createOpenRecordingMcpServer(opts: OpenRecordingMcpOptions): McpServer;
+declare function createOpenRecordingMcpHandler(opts: OpenRecordingMcpOptions): {
+  /**
+   * These tools hold a microphone and write to the user's disk, so a page in
+   * the browser must not be able to drive them. Rejecting unexpected Host and
+   * Origin headers is what closes the DNS-rebinding path onto a loopback
+   * endpoint.
+   */
+  fetch: (request: Request) => Promise<Response>;
+  close: () => Promise<void>;
+  notify: import("@modelcontextprotocol/server").ServerNotifier;
+  bus: import("@modelcontextprotocol/server").ServerEventBus;
+};
+/** Connect/Express-style middleware, for mounting on the dev server. */
+declare function createOpenRecordingMcpMiddleware(opts: OpenRecordingMcpOptions): import("@modelcontextprotocol/node").NodeMcpRequestHandler;
+//#endregion
+export { OpenRecordingMcpOptions, createOpenRecordingMcpHandler, createOpenRecordingMcpMiddleware, createOpenRecordingMcpServer };

package/dist/index.js

@@ -0,0 +1,229 @@
+import { toNodeHandler } from "@modelcontextprotocol/node";
+import { McpServer, createMcpHandler, hostHeaderValidationResponse, localhostAllowedHostnames, localhostAllowedOrigins, originValidationResponse } from "@modelcontextprotocol/server";
+import { OpsError, cancelRecording, deleteRecording, listRecordings, makeContext, pauseRecording, readNotes, readRecording, readSubtitles, readTranscript, recorderStatus, renameRecording, resumeRecording, searchTranscripts, startRecording, stopRecording, tagRecording, transcribeEnvironment, transcribeRecording, writeNotes } from "@open-recording/core/ops";
+import { z } from "zod";
+//#region src/tools.ts
+/**
+* Every tool is a thin wrapper over `@open-recording/core/ops` — the same
+* functions the dev server calls for the studio page. An agent and a person
+* therefore share one recorder: whoever presses stop, the other one sees it.
+*/
+/** Tools return text; JSON payloads go through as pretty-printed text blocks. */
+function ok(value) {
+	return { content: [{
+		type: "text",
+		text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+	}] };
+}
+/**
+* An OpsError is a refusal the caller can act on (503 no studio connected, 409
+* already recording), so it comes back as a tool error rather than a transport
+* failure.
+*/
+async function run(fn) {
+	try {
+		return ok(await fn());
+	} catch (err) {
+		if (err instanceof OpsError) return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: `${err.status}: ${err.message}`
+			}]
+		};
+		throw err;
+	}
+}
+function registerTools(server, ctx) {
+	server.registerTool("recorder_status", {
+		title: "Recorder status",
+		description: "Whether anything is recording or paused, and whether a studio page is connected to record through. Check this before starting.",
+		inputSchema: z.object({})
+	}, () => run(() => recorderStatus(ctx)));
+	server.registerTool("start_recording", {
+		title: "Start recording",
+		description: "Press record on whatever the studio is holding — a microphone, or a browser tab with its picture and audio. Returns once the studio confirms it is capturing; fails if no studio is connected or nothing is armed. One recording at a time.",
+		inputSchema: z.object({
+			title: z.string().optional().describe("what this recording is, e.g. \"Weekly sync\""),
+			tags: z.array(z.string()).optional(),
+			note: z.string().optional().describe("context worth keeping beside the audio")
+		})
+	}, ({ title, tags, note }) => run(() => startRecording(ctx, {
+		...title ? { title } : {},
+		...tags ? { tags } : {},
+		...note ? { note } : {}
+	})));
+	server.registerTool("stop_recording", {
+		title: "Stop recording",
+		description: "Stop the open recording and finalize the file — from paused too, with no need to resume first. Pass transcribe to run whisper.cpp immediately, which blocks until the transcription finishes.",
+		inputSchema: z.object({
+			transcribe: z.boolean().optional().describe("transcribe as soon as the audio lands"),
+			language: z.string().optional().describe("language code for the transcription, or `auto`")
+		})
+	}, ({ transcribe, language }) => run(async () => {
+		const meta = await stopRecording(ctx);
+		if (!transcribe) return meta;
+		const result = await transcribeRecording(ctx, meta.id, { ...language ? { language } : {} });
+		return {
+			...meta,
+			transcript: result
+		};
+	}));
+	server.registerTool("pause_recording", {
+		title: "Pause recording",
+		description: "Pause without closing the recording — the audio stays one file, with the paused span simply absent from it. Use this for an interruption; use stop_recording when the session is over.",
+		inputSchema: z.object({})
+	}, () => run(() => pauseRecording(ctx)));
+	server.registerTool("resume_recording", {
+		title: "Resume recording",
+		description: "Carry on capturing into the recording that is paused.",
+		inputSchema: z.object({})
+	}, () => run(() => resumeRecording(ctx)));
+	server.registerTool("cancel_recording", {
+		title: "Cancel recording",
+		description: "Stop the open recording and delete its audio. Use when the recording was a mistake.",
+		inputSchema: z.object({})
+	}, () => run(() => cancelRecording(ctx)));
+	server.registerTool("list_recordings", {
+		title: "List recordings",
+		description: "Every recording with its id, title, length, and whether it has been transcribed.",
+		inputSchema: z.object({})
+	}, () => run(() => listRecordings(ctx)));
+	server.registerTool("read_recording", {
+		title: "Read recording metadata",
+		description: "Full metadata for one recording, including transcription details when present.",
+		inputSchema: z.object({ id: z.string() })
+	}, ({ id }) => run(() => readRecording(ctx, id)));
+	server.registerTool("transcribe_recording", {
+		title: "Transcribe recording",
+		description: "Run local whisper.cpp over a recording and store the transcript beside the audio. Refuses when a transcript exists unless force is set.",
+		inputSchema: z.object({
+			id: z.string(),
+			language: z.string().optional().describe("language code, or `auto` (the default)"),
+			model: z.string().optional().describe("path to a ggml model, overriding the configured one"),
+			force: z.boolean().optional()
+		})
+	}, ({ id, language, model, force }) => run(() => transcribeRecording(ctx, id, {
+		...language ? { language } : {},
+		...model ? { model } : {},
+		...force ? { force } : {}
+	})));
+	server.registerTool("read_transcript", {
+		title: "Read transcript",
+		description: "The stored transcript. `markdown` (default) carries timestamps you can cite; `text` is prose only; `segments` is the timed data.",
+		inputSchema: z.object({
+			id: z.string(),
+			view: z.enum([
+				"markdown",
+				"text",
+				"segments"
+			]).optional()
+		})
+	}, ({ id, view }) => run(() => readTranscript(ctx, id, view ?? "markdown")));
+	server.registerTool("read_subtitles", {
+		title: "Read subtitles",
+		description: "The transcript as subtitle cues — `srt` for an editor, `vtt` for a player. Written when a recording is transcribed.",
+		inputSchema: z.object({
+			id: z.string(),
+			format: z.enum(["srt", "vtt"]).optional()
+		})
+	}, ({ id, format }) => run(() => readSubtitles(ctx, id, format ?? "srt")));
+	server.registerTool("search_transcripts", {
+		title: "Search transcripts",
+		description: "Substring search across every stored transcript. Hits carry the recording id and the millisecond offset, so you can point at the moment.",
+		inputSchema: z.object({
+			query: z.string(),
+			limit: z.number().int().positive().max(100).optional()
+		})
+	}, ({ query, limit }) => run(() => searchTranscripts(ctx, query, limit ?? 20)));
+	server.registerTool("write_notes", {
+		title: "Write notes",
+		description: "Store your own Markdown beside the audio — a summary, action items, decisions. Overwrites any previous notes.",
+		inputSchema: z.object({
+			id: z.string(),
+			notes: z.string()
+		})
+	}, ({ id, notes }) => run(() => writeNotes(ctx, id, notes)));
+	server.registerTool("read_notes", {
+		title: "Read notes",
+		description: "The Markdown notes stored beside a recording.",
+		inputSchema: z.object({ id: z.string() })
+	}, ({ id }) => run(() => readNotes(ctx, id)));
+	server.registerTool("rename_recording", {
+		title: "Rename recording",
+		description: "Change a recording’s title. The id never moves — it is the folder on disk.",
+		inputSchema: z.object({
+			id: z.string(),
+			title: z.string()
+		})
+	}, ({ id, title }) => run(() => renameRecording(ctx, id, title)));
+	server.registerTool("tag_recording", {
+		title: "Tag recording",
+		description: "Replace a recording’s tags.",
+		inputSchema: z.object({
+			id: z.string(),
+			tags: z.array(z.string())
+		})
+	}, ({ id, tags }) => run(() => tagRecording(ctx, id, tags)));
+	server.registerTool("delete_recording", {
+		title: "Delete recording",
+		description: "Permanently delete a recording — audio, transcript, and notes. Confirm with the user first.",
+		inputSchema: z.object({ id: z.string() })
+	}, ({ id }) => run(() => deleteRecording(ctx, id)));
+	server.registerTool("transcription_environment", {
+		title: "Transcription environment",
+		description: "Which whisper.cpp binary, model, and ffmpeg the workspace resolved. Read this when a transcription is refused with a 503.",
+		inputSchema: z.object({})
+	}, () => run(() => transcribeEnvironment(ctx)));
+}
+//#endregion
+//#region src/index.ts
+function contextFor(opts) {
+	return makeContext({
+		userCwd: opts.userCwd,
+		coreVersion: opts.version ?? "0.0.0",
+		...opts.config ? { config: opts.config } : {}
+	});
+}
+/**
+* A fresh server per request. The recorder state it acts on is not held here —
+* it lives in the dev server process this endpoint is mounted on — so there is
+* nothing worth carrying between calls, which is the stateless shape that lets
+* any client connect without a session handshake.
+*/
+function createOpenRecordingMcpServer(opts) {
+	const server = new McpServer({
+		name: "open-recording",
+		version: opts.version ?? "0.0.0",
+		title: "open-recording"
+	});
+	registerTools(server, contextFor(opts));
+	return server;
+}
+function createOpenRecordingMcpHandler(opts) {
+	const allowedHostnames = [...localhostAllowedHostnames(), ...opts.allowedHosts ?? []];
+	const allowedOrigins = [...localhostAllowedOrigins(), ...opts.allowedHosts ?? []];
+	const handler = createMcpHandler(() => createOpenRecordingMcpServer(opts));
+	return {
+		...handler,
+		/**
+		* These tools hold a microphone and write to the user's disk, so a page in
+		* the browser must not be able to drive them. Rejecting unexpected Host and
+		* Origin headers is what closes the DNS-rebinding path onto a loopback
+		* endpoint.
+		*/
+		fetch: async (request) => {
+			const hostRejection = hostHeaderValidationResponse(request, allowedHostnames);
+			if (hostRejection) return hostRejection;
+			const originRejection = originValidationResponse(request, allowedOrigins);
+			if (originRejection) return originRejection;
+			return handler.fetch(request);
+		}
+	};
+}
+/** Connect/Express-style middleware, for mounting on the dev server. */
+function createOpenRecordingMcpMiddleware(opts) {
+	return toNodeHandler(createOpenRecordingMcpHandler(opts));
+}
+//#endregion
+export { createOpenRecordingMcpHandler, createOpenRecordingMcpMiddleware, createOpenRecordingMcpServer };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@open-recording/mcp",
+  "version": "0.2.0",
+  "description": "MCP server for open-recording — lets any agent framework press record, stop, transcribe, and read back the transcript.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "recording",
+    "transcription",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Simon Liu",
+    "url": "https://github.com/LiuYuWei"
+  },
+  "homepage": "https://github.com/simonliu-ai-product/open-recording",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simonliu-ai-product/open-recording.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/simonliu-ai-product/open-recording/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@open-recording/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3",
+    "@open-recording/core": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}