samuraizer 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be 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).
+
+## [0.2.0] - 2026-05-06
+
+### Added
+- MCP server support
+- MCP tools for:
+    - audio normalization
+    - transcription
+    - transcript summarization
+    - action items extraction
+    - decision extraction
+    - full recording processing pipeline
+-Compatibility with MCP clients such a Claude Desktop and MCP Inspector
+
+
+## [0.1.0] - 2026-04-26
+
+### Added
+
+- Initial public release
+- `process` command: full pipeline from audio to transcript, summary, action items, and decisions
+- Individual commands: `normalize`, `summarize`, `actions`, `decisions`
+- Configuration system: `samuraizer init` and `samuraizer config` commands
+- Resume processing: skip steps with existing outputs (use `--force` to recompute)
+- Local-first: uses Whisper (whisper.cpp) and Ollama, no cloud APIs required
+- Output formats: plain text (`transcript.txt`, `summary.txt`, `report.txt`) and JSON (`action-items.json`, `decisions.json`)

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 UladzKha
+
+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 THEREOF.

package/README.md

@@ -1,72 +1,106 @@
 # Samuraizer
 
-Local-first CLI for meeting transcription and analysis.
+Turn meeting recordings into transcripts, summaries, action items, and decisions — entirely on your machine. No cloud, no subscriptions, no data leaving your network.
 
-Samuraizer processes audio recordings and generates:
-- transcript
-- summary
-- action items
-- decisions
-- report
+![Samuraizer demo](https://raw.githubusercontent.com/UladzKha/samuraizer-cli/main/assets/demo.gif)
 
-All processing is done locally using tools like Whisper and Ollama
+## Why Samuraizer
 
+- **Fully local.** Your recordings never leave your machine.
+- **CLI-first.** Scriptable, automatable, integrates with cron, Git hooks, Obsidian workflows.
+- **Resumable.** Crashed mid-pipeline? Re-run picks up where it left off.
+- **Model-agnostic.** Works with any Ollama-compatible LLM — pick what fits your hardware.
+- **Free.** No subscriptions, no per-minute pricing.
 
-## ✨ Features
+## 💻 System Requirements
 
-- 🎙 Transcribe audio recordings (Whisper)
-- 🧠 Generate summaries (local LLM via Ollama)
-- ✅ Extract action items
-- 📌 Extract decisions
-- ⚡ Resume processing (skip already processed steps)
-- 🔧 Simple CLI + config system
-- 🔒 Local-first (no cloud required)
+| RAM    | Recommended model       |
+| ------ | ----------------------- |
+| 8 GB   | `qwen2.5:3b`            |
+| 16 GB  | `qwen2.5:7b`            |
+| 32 GB+ | `qwen2.5:14b` (default) |
 
+Apple Silicon (M1/M2/M3/M4) and recent x86 CPUs with AVX2 are recommended.
+Whisper transcription is CPU/Metal-accelerated; LLM inference uses Ollama's defaults.
 
-## 📦 Installation
+## ⚙️ Prerequisites
 
-```bash
-npm install -g samuraizer
-```
+Install the required tools:
 
-## ⚙️ Prerequisites
+- **Node.js** ≥ 20 — [nodejs.org](https://nodejs.org/)
+- **ffmpeg** — for audio processing
+- **whisper-cli** — from [whisper.cpp](https://github.com/ggerganov/whisper.cpp)
+- **Ollama** — [ollama.com](https://ollama.com/)
+
+Start Ollama and pull a model:
 
-Make sure you have installed:
 ```bash
-Node.js >= 20
-ffmpeg
-whisper-cli (whisper.cpp)
-Ollama
-Start Ollama
 ollama serve
 ollama pull qwen2.5:14b
 ```
 
+## 📦 Installation
+
+```bash
+npm install -g samuraizer
+```
+
 ## 🚀 Quick Start
+
 ```bash
 samuraizer init
 samuraizer process meeting.m4a
 ```
 
-## ⚙️ Configuration
+On a 30-minute recording this typically takes 3–5 minutes on Apple Silicon and 8–15 minutes on x86 CPUs, depending on the model.
 
-Samuraizer uses a global JSON config file.
+## 🧪 Commands
+
+### Process an audio file
 
-### Initialize config
 ```bash
-samuraizer init
+samuraizer process meeting.m4a              # full pipeline
+samuraizer process meeting.m4a --verbose    # show detailed metadata
+samuraizer process meeting.m4a --force      # recompute all steps
+samuraizer process meeting.m4a --verbose --force
 ```
 
-### Config location
-* **macOS**: `~/Library/Application Support/samuraizer/config.json`
-* **Linux**: `~/.config/samuraizer/config.json`
-* **Windows**: `%AppData%/samuraizer/config.json`
+### Run individual steps
+
+```bash
+samuraizer normalize input.m4a output.wav   # normalize audio for Whisper
+samuraizer summarize transcript.txt         # generate summary from transcript
+samuraizer actions transcript.txt           # extract action items
+samuraizer decisions transcript.txt         # extract decisions
+```
+
+### Configuration
 
-### View config
 ```bash
-samuraizer config get
+samuraizer init           # create default config file
+samuraizer config path    # show config file location
+samuraizer config get     # print resolved config as JSON
 ```
+
+### Other
+
+```bash
+samuraizer --help
+samuraizer --version
+```
+
+## ⚙️ Configuration
+
+Samuraizer uses a global JSON config file.
+
+### Config location
+
+- **macOS**: `~/Library/Application Support/samuraizer/config.json`
+- **Linux**: `~/.config/samuraizer/config.json`
+- **Windows**: `%AppData%/samuraizer/config.json`
+
 ### Example config
+
 ```json
 {
   "model": "qwen2.5:14b",
@@ -77,7 +111,7 @@ samuraizer config get
 }
 ```
 
-### 🧩 Config fields
+### Config fields
 
 - **model** — LLM model used for analysis (summary, action items, decisions)
 - **ollamaBaseUrl** — URL where Ollama is running
@@ -85,122 +119,136 @@ samuraizer config get
 - **ffmpegCommand** — Command used for audio processing
 - **ffprobeCommand** — Command used for audio inspection
 
+## 📂 Example output
 
-## 🧪 Commands
-
-### Show help
+After processing, you'll find structured files in `output/<recording-name>/`:
 
-```bash
-samuraizer --help
 ```
-
-### Show version
-
-```bash
-samuraizer --version
+output/meeting/
+  transcript.txt
+  summary.txt
+  action-items.json
+  decisions.json
+  report.txt
 ```
 
-## 🚀 Full pipeline
+**`summary.txt`**
 
-### Process an audio recording:
-```bash
-samuraizer process meeting.m4a
 ```
-
-### Show detailed metadata after processing:
-```bash
-samuraizer process meeting.m4a --verbose
+Team standup focused on Q2 roadmap and infrastructure migration.
+The frontend team will start the Next.js upgrade next week...
 ```
 
-### Recompute all steps even if outputs already exist:
-```bash
-samuraizer process meeting.m4a --force
-```
+**`action-items.json`**
 
-### You can combine flags:
-```bash
-samuraizer process meeting.m4a --verbose --force
+```json
+[
+  {
+    "owner": "Alice",
+    "task": "Set up staging environment for migration testing",
+    "deadline": "by end of week"
+  },
+  {
+    "owner": "Bob",
+    "task": "Review the auth refactor PR",
+    "deadline": null
+  }
+]
+```
+
+**`decisions.json`**
+
+```json
+[
+  {
+    "decision": "Adopt Next.js 15 for the new dashboard",
+    "rationale": "Better SSR and built-in App Router support"
+  }
+]
 ```
 
-## 🎛 Individual commands
+## 🔁 Resume behavior
 
-### Normalize audio to Whisper-compatible WAV:
-```bash
-samuraizer normalize input.m4a output.wav
-```
+Samuraizer skips steps whose output files already exist. If processing crashes or you stop it mid-pipeline, just re-run the same command — completed steps are reused.
 
-### Summarize a transcript file:
-```bash
-samuraizer summarize transcript.txt
-```
+Use `--force` to recompute everything from scratch.
 
-### Extract action items from a transcript file:
-```bash
-samuraizer actions transcript.txt
-```
+## ⚠️ Troubleshooting
+
+### Ollama not running
 
-### Extract decisions from a transcript file:
 ```bash
-samuraizer decisions transcript.txt
+ollama serve
 ```
 
+### Ollama on a non-default port
 
-## ⚙️ Configuration commands
+Update `ollamaBaseUrl` in your config:
 
-### Create the default config file:
-```bash
-samuraizer init
+```json
+{
+  "ollamaBaseUrl": "http://127.0.0.1:11500"
+}
 ```
 
-### Print config file path:
-```bash
-samuraizer config path
-```
+### Out of memory during analysis
+
+Switch to a smaller model:
 
-### Print resolved config as JSON:
 ```bash
-samuraizer config get
+ollama pull qwen2.5:7b
 ```
 
+Then update `model` in your config to `qwen2.5:7b` (or `qwen2.5:3b` on machines with 8 GB RAM).
 
-### 📂 Output
-```json
-output/<file-name>/
-  transcript.txt
-  summary.txt
-  action-items.json
-  decisions.json
-  report.txt
-  ```
+### Model not found
+
+Make sure the model in your config is actually pulled:
 
+```bash
+ollama list
+ollama pull <model-name>
+```
 
-### 🔁 Resume Behavior
+### `whisper-cli` not in PATH
 
-Samuraizer skips already processed steps.
+Build [whisper.cpp](https://github.com/ggerganov/whisper.cpp) and ensure the binary is on your `PATH`, or set the absolute path in `whisperCommand` in your config.
 
-Use `--force` to rebuild everything.
+### `ffmpeg` not found
 
+**macOS:**
 
-### ⚠️ Common Issues
-#### Ollama not running
 ```bash
-ollama serve
+brew install ffmpeg
 ```
 
-#### ffmpeg not found
+**Linux:**
 
-macOS:
 ```bash
-brew install ffmpeg
+# Debian / Ubuntu
+sudo apt install ffmpeg
+
+# Arch / CachyOS
+sudo pacman -S ffmpeg
+
+# Fedora
+sudo dnf install ffmpeg
 ```
 
-Linux:
-```bash
-apt install ffmpeg
+**Windows:**
+
+```powershell
+winget install Gyan.FFmpeg
 ```
 
-### 📄 License
+## 📝 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+## 📄 License
+
+MIT — see [LICENSE](./LICENSE).
 
-ISC
+## 🔗 Source code
 
----
+Available on GitHub: [github.com/UladzKha/samuraizer-cli](https://github.com/UladzKha/samuraizer-cli)

package/dist/cli/index.js

@@ -7,11 +7,17 @@ import { getConfigFilePath } from "../config/paths.js";
 import { processMeeting } from "../orchestrators/process-meeting.js";
 import { runTool } from "../shared/tool-definition.js";
 import { tools } from "../shared/tool-registry.js";
+import { startMcpServer } from "../mcp/server.js";
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8'));
 const program = new Command();
 program
     .name("samuraizer")
     .description("Transform meeting recordings into structured knowledge")
-    .version("0.0.1");
+    .version(pkg.version);
 program
     .command("process")
     .description("Run the full pipeline on an audio recording")
@@ -172,4 +178,16 @@ configCommand
         process.exitCode = 1;
     }
 });
+program
+    .command("mcp")
+    .description("Start the MCP server (stdio transport)")
+    .action(async () => {
+    try {
+        await startMcpServer();
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+});
 program.parse(process.argv);

package/dist/mcp/server.js

@@ -0,0 +1,188 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { createContext } from '../tools/context.js';
+import { runTool } from '../shared/tool-definition.js';
+import { tools } from '../shared/tool-registry.js';
+const server = new McpServer({
+    name: 'samuraizer',
+    version: '0.1.0',
+}, {
+    instructions: 'Use process_recording for the full pipeline. ' +
+        'Use individual tools (normalize_audio, transcribe_audio, summarize_transcript, ' +
+        'extract_action_items, extract_decisions) for step-by-step processing.',
+});
+server.registerTool('normalize_audio', {
+    title: 'Normalize Audio',
+    description: 'Normalize an audio file to 16kHz mono PCM WAV format required by Whisper.',
+    inputSchema: {
+        inputPath: z.string().describe('Absolute path to the source audio file'),
+        outputPath: z.string().describe('Absolute path for the output WAV file'),
+    },
+}, async ({ inputPath, outputPath }) => {
+    const ctx = await createContext();
+    try {
+        const result = await runTool(tools.normalize_audio, {
+            inputPath,
+            outputPath,
+            ffmpegCommand: ctx.config.ffmpegCommand,
+        });
+        return {
+            content: [{ type: 'text', text: result.normalizedAudioPath }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error normalizing audio: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('transcribe_audio', {
+    title: 'Transcribe Audio',
+    description: 'Transcribe an audio file using whisper.cpp. Returns the transcript text.',
+    inputSchema: {
+        filePath: z.string().describe('Absolute path to the audio file'),
+    },
+}, async ({ filePath }) => {
+    const ctx = await createContext();
+    try {
+        const result = await runTool(tools.transcribe_audio, {
+            audioPath: filePath,
+            outputDir: ctx.config.outputDir ?? 'output',
+            modelPath: ctx.config.whisperModelPath,
+            language: ctx.config.language,
+            whisperCommand: ctx.config.whisperCommand,
+        });
+        return {
+            content: [{ type: 'text', text: result.text }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error transcribing audio: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('summarize_transcript', {
+    title: 'Summarize Transcript',
+    description: 'Generate a concise meeting summary from transcript text.',
+    inputSchema: {
+        transcriptText: z.string().describe('Full transcript text to summarize'),
+        model: z.string().optional().describe('Ollama model to use (optional)'),
+    },
+}, async ({ transcriptText, model }) => {
+    const ctx = await createContext();
+    try {
+        const result = await runTool(tools.summarize_transcript, {
+            transcriptText,
+            model: model ?? ctx.config.model,
+            ollamaBaseUrl: ctx.config.ollamaBaseUrl,
+        });
+        return {
+            content: [{ type: 'text', text: result.summary }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error summarizing transcript: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('extract_action_items', {
+    title: 'Extract Action Items',
+    description: 'Extract action items from a meeting transcript. Returns a JSON list of tasks with owner and due date.',
+    inputSchema: {
+        transcriptText: z.string().describe('Full transcript text'),
+        model: z.string().optional().describe('Ollama model to use (optional)'),
+    },
+}, async ({ transcriptText, model }) => {
+    const ctx = await createContext();
+    try {
+        const result = await runTool(tools.extract_action_items, {
+            transcriptText,
+            model: model ?? ctx.config.model,
+            ollamaBaseUrl: ctx.config.ollamaBaseUrl,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error extracting action items: ${message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('extract_decisions', {
+    title: 'Extract Decisions',
+    description: 'Extract confirmed decisions from a meeting transcript. Returns a JSON list of decisions.',
+    inputSchema: {
+        transcriptText: z.string().describe('Full transcript text'),
+        model: z.string().optional().describe('Ollama model to use (optional)'),
+    },
+}, async ({ transcriptText, model }) => {
+    const ctx = await createContext();
+    try {
+        const result = await runTool(tools.extract_decisions, {
+            transcriptText,
+            model: model ?? ctx.config.model,
+            ollamaBaseUrl: ctx.config.ollamaBaseUrl,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error extracting decisions: ${message}` }],
+        };
+    }
+});
+server.registerTool('process_recording', {
+    title: 'Process Recording',
+    description: 'Run the full Samuraizer pipeline on an audio file. Returns summary, action items, decisions, and output file paths.',
+    inputSchema: {
+        filePath: z.string().describe('Absolute path to the audio file'),
+        model: z.string().optional().describe('Ollama model to use (optional)'),
+    },
+}, async ({ filePath, model }) => {
+    const ctx = await createContext();
+    try {
+        const { processMeeting } = await import('../orchestrators/process-meeting.js');
+        const result = await processMeeting({
+            inputPath: filePath,
+            outputRootDir: ctx.config.outputDir,
+            model: model ?? ctx.config.model,
+            ollamaBaseUrl: ctx.config.ollamaBaseUrl,
+            whisperCommand: ctx.config.whisperCommand,
+            whisperModelPath: ctx.config.whisperModelPath,
+            language: ctx.config.language,
+            ffmpegCommand: ctx.config.ffmpegCommand,
+            ffprobeCommand: ctx.config.ffprobeCommand,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: `Error processing recording: ${message}` }],
+            isError: true,
+        };
+    }
+});
+export async function startMcpServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('Samuraizer MCP server started and listening for requests...\n');
+}

package/dist/tools/context.js

@@ -0,0 +1,7 @@
+import { loadConfig } from "../config/load.js";
+export async function createContext() {
+    return {
+        config: await loadConfig(),
+        logger: console,
+    };
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "samuraizer",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "samuraizer": "./dist/cli/index.js"
@@ -10,26 +10,45 @@
     "process": "tsx src/cli/index.ts process",
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "mcp": "tsx src/cli/index.ts mcp",
+    "mcp:dist": "node dist/cli/index.js mcp"
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"
   },
   "keywords": [
-    "cli",
     "transcription",
-    "meetings",
-    "ollama",
+    "meeting-notes",
     "whisper",
-    "local-first"
+    "ollama",
+    "local-llm",
+    "speech-to-text",
+    "cli",
+    "self-hosted",
+    "privacy"
   ],
-  "license": "ISC",
-  "description": "CLI tool for meeting transcription and summarization",
+  "license": "MIT",
+  "description": "Local-first CLI that turns meeting recordings into transcripts, summaries, action items, and decisions",
+  "author": "Uladz Kha <UladzKha@users.noreply.github.com>",
+  "funding": "https://github.com/sponsors/UladzKha",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UladzKha/samuraizer-cli.git"
+  },
+  "homepage": "https://github.com/UladzKha/samuraizer-cli#readme",
+  "bugs": {
+    "url": "https://github.com/UladzKha/samuraizer-cli/issues"
+  },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.3",
     "execa": "^9.6.1",
     "zod": "^4.3.6"
@@ -39,4 +58,4 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }
-}
+}