Samuraizer

@samuraizer/mcp-server

AI エージェントが会議の録音データ（文字起こし、要約、アクションアイテム、決定事項）にアクセスできる、ローカルファーストの MCP サーバーです。データをクラウドに送信する必要はありません。

Samuraizer 向けの Model Context Protocol サーバーです。処理済みの会議データを、stdio 経由で AI エージェント（Claude Desktop、Claude Code、MCP Inspector など）に公開します。

ツールの概要

• normalize_audio — Whisper で必要な 16kHz モノラル PCM WAV 形式に音声ファイルを正規化します。
• transcribe_audio — whisper.cpp を使用して音声ファイルを文字起こしします。文字起こしテキストを返します。
• summarize_transcript — 文字起こしテキストから簡潔な会議の要約を生成します。
• extract_action_items — 会議の文字起こしからアクションアイテムを抽出します。担当者と期限を含むタスクの JSON リストを返します。
• extract_decisions — 会議の文字起こしから確定した決定事項を抽出します。決定事項の JSON リストを返します。
• process_recording — 音声ファイルに Samuraizer のパイプライン全体を実行します。要約、アクションアイテム、決定事項、出力ファイルのパスを返します。
• search_meetings — 要約テキスト、名前、アクションアイテム、決定事項で会議を検索します。文字起こしは検索対象ではありません。文字起こしを確認するには get_meeting を使用してください。スニペット付きの関連度順の検索結果を返します。
• list_meetings — 処理済みの会議をすべて、新しいものから順に一覧表示します。結果数を指定して制限することもできます。
• get_meeting — ID を指定して、特定の会議の処理済み出力全体を取得します。
• meeting://{id} (リソース) — ULID でアクセスできる、単一の処理済み会議です。

各ツールの入力と出力の詳細は、以下のツールをご覧ください。

サーバーは 2 つのモードを提供します。

• クエリモード — 処理済みの会議を、構造化データまたは MCP リソースとして一覧表示・取得します。読み取り専用で、実行時に LLM や音声関連の依存関係は必要ありません。
• 処理モード — 音声ファイルに Samuraizer のパイプライン全体（正規化 → 文字起こし → 要約 → アクションアイテム／決定事項の抽出）を実行します。whisper-cli、ffmpeg、ffprobe、および起動中の Ollama インスタンスなど、samuraizer 本体と同じローカルツールチェーンが必要です。

すべてのデータはローカルに保存されます。サーバーはマシン上のディレクトリから会議データを読み込み、外部サービスにデータを送信することはありません。

前提条件

このパッケージは設定とパイプラインに @samuraizer/cli を使用します。MCP サーバーを使用する前に、CLI をインストールして初期化してください。

npm install -g @samuraizer/cli
samuraizer init

生成された設定を編集し（パスは samuraizer config path で表示されます）、meetingsDir が処理済みの会議データを保存しているディレクトリを指していることを確認してください。MCP サーバーは同じディレクトリから読み込みます。

処理モードでは、Samuraizer の実行時依存関係もインストールして設定する必要があります。whisper.cpp の whisper-cli、ffmpeg／ffprobe、およびモデルを取得済みの実行中の Ollama サーバーが必要です。セットアップの詳細は、Samuraizer のメイン READMEをご覧ください。

クエリモードのみ（list_meetings、get_meeting、meeting:// リソース）の場合、実行時の依存関係は不要です。meetingsDir にデータがあれば使用できます。

インストール

npm install -g @samuraizer/mcp-server

これにより、PATH 上で samuraizer-mcp バイナリを使用できるようになります。

使用方法

サーバーを直接起動する

samuraizer-mcp

サーバーは stdio 経由で MCP を使用します。シェルから対話的に使用するものではなく、Claude Desktop や MCP Inspector などの MCP クライアントから起動することを想定しています。

MCP Inspector で確認する

npx @modelcontextprotocol/inspector samuraizer-mcp

ツールやリソースを一覧表示し、引数を指定して呼び出して応答を確認できるブラウザー UI が開きます。デバッグに便利です。

Claude Desktop から接続する

サーバーを Claude Desktop の設定ファイルに追加します。

• macOS / Linux：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または ~/.config/Claude/claude_desktop_config.json（Linux）
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "samuraizer": {
      "command": "samuraizer-mcp"
    }
  }
}

Claude Desktop で samuraizer-mcp が見つからない場合（fnm、nvm、volta などのバージョンマネージャーでは PATH の問題がよく発生します）、代わりに絶対パスを使用してください。which samuraizer-mcp で場所を確認してから、次のようにします。

{
  "mcpServers": {
    "samuraizer": {
      "command": "/absolute/path/to/samuraizer-mcp"
    }
  }
}

環境変数を使って、サーバーごとにミーティングディレクトリを上書きすることもできます。

{
  "mcpServers": {
    "samuraizer-personal": {
      "command": "samuraizer-mcp",
      "env": {
        "SAMURAIZER_MEETINGS_DIR": "/Users/me/personal-meetings"
      }
    },
    "samuraizer-work": {
      "command": "samuraizer-mcp",
      "env": {
        "SAMURAIZER_MEETINGS_DIR": "/Users/me/work-meetings"
      }
    }
  }
}

設定を編集した後、Claude Desktop を再起動してください。

Claude Code から接続する

claude mcp add samuraizer samuraizer-mcp

CLI から MCP サーバーを管理する方法については、Claude Code の MCP ドキュメントをご覧ください。

設定

MCP サーバーは @samuraizer/cli と同じ設定ファイルを読み込みます。サーバー専用の設定ファイルはありません。

環境変数による上書き

すべての設定フィールドは環境変数で上書きできます。これは、異なるコンテキストでサーバーを実行する場合（例：プロジェクトごとに MCP サーバーを1つ実行する場合）に便利です。

変数	対応する設定
SAMURAIZER_MEETINGS_DIR	meetingsDir
SAMURAIZER_MODEL	model
SAMURAIZER_OLLAMA_BASE_URL	ollamaBaseUrl
SAMURAIZER_WHISPER_COMMAND	whisperCommand
SAMURAIZER_WHISPER_MODEL_PATH	whisperModelPath
SAMURAIZER_WHISPER_DEVICE	whisperDevice
SAMURAIZER_WHISPER_PROMPT	whisperPrompt
SAMURAIZER_WHISPER_CARRY_INITIAL_PROMPT	whisperCarryInitialPrompt
SAMURAIZER_LANGUAGE	language
SAMURAIZER_FFMPEG_COMMAND	ffmpegCommand
SAMURAIZER_FFPROBE_COMMAND	ffprobeCommand
SAMURAIZER_LLM_CONCURRENCY	llmConcurrency

環境変数は設定ファイルの値より優先されます。ブール値には 1/0、true/false、yes/no、on/off を使用できます。

llmConcurrency のデフォルト値は 1 です。そのため、process_recording はすべてのハードウェアで、要約、アクションアイテム、決定事項の抽出を順番に実行します。値に 2 または 3 を指定すると、Ollama リクエストが並列実行されます。この設定には、追加の KV キャッシュスロットを確保できるだけの空き VRAM が必要です。

ツール

クエリモード

search_meetings

要約テキスト、ミーティング名、アクションアイテム、決定事項を対象に、処理済みのミーティングを検索します。

文字起こしテキストは意図的に検索対象から除外されています。これらは上記のフィールドより桁違いに大きく、クエリのたびにスキャンすると拡張性が損なわれるためです。文字起こしが必要な場合は get_meeting を使用してください。

入力：

• query (文字列、必須) — 検索クエリ。大文字と小文字は区別されません。クエリ構文をご覧ください。
• limit (整数、任意) — 返す結果の最大数（デフォルトは 10）。

戻り値： ランク付けされた結果の JSON 配列。各結果には id、name、generated_at、duration_sec、score、matched_in（summary、name、action_items、decisions のいずれか）、および最も一致した箇所の前後を含む snippet が含まれます。結果は一致したフィールドの数に基づいてランク付けされます。要約での一致は、名前、アクションアイテム、決定事項での一致より重く評価されます。同点の場合は新しいものが上位になります。すべてのミーティングを列挙せずに、特定のミーティングを探すのに便利です。

クエリ構文

クエリは単語に分割され、すべての単語が見つかった場合にのみミーティングが一致します。単語が同じフィールドに含まれている必要はありません。そのため、patient id post log は、要約に患者 ID が記載され、アクションアイテムに post log が記載されているミーティングに一致します。

各単語は部分文字列として一致するため、export を検索すると exporter も見つかります。

完全一致のフレーズを指定するには、クエリを二重引用符で囲みます。

patient id post log      → all four words, anywhere in the searched fields
"patient id post log"    → that exact run of characters, in one field

クエリ全体がそのまま含まれるミーティングは、同じ単語が散在しているだけのミーティングより高いスコアになります。そのため、完全一致する結果が引き続き上位に表示されます。

list_meetings

処理済みのミーティングを新しい順に一覧表示します。

入力：

• limit (integer, optional) — 返す結果の最大数です。

戻り値： ミーティングの概要（id、name、generated_at、summary_preview、participant_count、duration_sec）を含む JSON 配列です。

get_meeting

特定のミーティングの処理済み出力全体を取得します。

入力：

• id (string, required) — ミーティング ID（ULID）です。

戻り値： 文字起こし、要約、アクションアイテム、決定事項、出所メタデータを含む、ミーティングの完全な JSON です。ミーティングが見つからない場合はエラーを返します。

処理モード

これらのツールは Samuraizer パイプラインの一部をオンデマンドで実行します。ローカルの実行時依存関係（whisper-cli、ffmpeg、Ollama）が必要です。

process_recording

音声ファイルに対してパイプライン全体を実行します。エージェント経由で録音を処理する場合に推奨されるエントリーポイントです。

入力：

• filePath (string, required) — 音声ファイルの絶対パスです。
• model (string, optional) — 使用する Ollama モデルです。設定済みのデフォルトにフォールバックします。

戻り値： 要約、アクションアイテム、決定事項、出力ファイルのパスを含む JSON です。

normalize_audio

音声ファイルを 16 kHz のモノラル PCM WAV（Whisper が必要とする形式）に正規化します。

入力： inputPath、outputPath（どちらも必須の絶対パス）。

transcribe_audio

whisper.cpp で音声ファイルを文字起こしします。

入力： filePath（必須の絶対パス）。

summarize_transcript

文字起こしテキストからミーティングの要約を生成します。

入力： transcriptText（必須）、model（任意）。

extract_action_items

文字起こしからアクションアイテムを抽出します。

入力： transcriptText（必須）、model（任意）。

extract_decisions

文字起こしから確定した決定事項を抽出します。

入力： transcriptText（必須）、model（任意）。

リソース

サーバーは、処理済みの各ミーティングを MCP リソースとして公開します。

• URI スキーム： meeting://{id}
• MIME タイプ： application/json
• コンテンツ： get_meeting が返すものと同一の、ミーティングの完全な JSON です。

リソースを一覧表示すると、meetingsDir 内のミーティングごとにエントリーが返されます。リソースを読み取ると、その完全なコンテンツが返されます。リソースを UI に表示するクライアント（例：Claude Desktop のリソースピッカー）にとって、リソースは特に便利です。

ミーティング出力形式

すべてのミーティング JSON は、ミーティングの構造、文字起こしのセグメント、要約、アクションアイテム、決定事項、出所メタデータを記述する、オープンな Samuraizer ミーティング出力スキーマに準拠しています。

スキーマと仕様は、memnex-spec パッケージにあります。

• JSON Schema（Draft 2020-12）：spec/meeting-output.schema.json
• 人間が読める仕様： spec/SPEC.md
• 例： spec/examples/

トラブルシューティング

Error: The config file is not created, please run 'samuraizer init'

MCP サーバーは CLI と同じ設定を使用します。まず @samuraizer/cli をインストールし、samuraizer init を実行してください。

サーバーは起動するが、list_meetings が空の配列を返す

meetingsDir が空であるか、そこにあるすべての meeting.json ファイルがスキーマ検証に失敗しています。サーバーはスキップした各無効なミーティングについて、構造化された警告を stderr に記録します。MCP サーバーを実行しているターミナル（または macOS の場合は Claude Desktop のログ ~/Library/Logs/Claude/mcp-server-samuraizer.log）を確認してください。

サーバー起動時の EACCES

ソースから npm run build を実行した後、dist/index.js の実行ビットを設定する必要がある場合があります。npm からインストールする場合は、パッケージの postbuild スクリプトが自動的に処理します。リポジトリをクローンした場合は、chmod +x dist/index.js が実行されたことを確認してください。

Claude Desktop にサーバーが接続されていないと表示される

よくある原因：

• samuraizer-mcp が Claude Desktop の参照する PATH にありません。絶対パスを使用してください。
• 設定ファイルが無効な JSON です。jq . < claude_desktop_config.json で検証してください。
• 設定ファイルがない、または設定が無効なため、サーバーの起動時にクラッシュしています。Claude Desktop の MCP ログを確認してください。

ライセンス

MIT — LICENSE を参照してください。

ソース

github.com/UladzKha/samuraizer-cli（モノレポ）