Samuraizer

Name: Samuraizer
Author: UladzKha

本地服务

github.com/UladzKha生产力27 周前更新

代码仓库

关于 Samuraizer

Samuraizer 是面向 Agent 的本地优先 MCP 服务，可处理和查询会议录音。数据保留在本机，并提供已处理会议的只读访问及本地音频处理流程。

主要功能

01使用 whisper.cpp 转录音频
02生成摘要并提取决策
03提取含负责人和截止日期的行动项
04搜索、列出和读取已处理会议
05将会议作为 MCP 资源提供

适用场景

01将录音处理为摘要和任务
02按摘要或决策查找会议
03读取转录文本和完整会议数据

MCP 相关

提供音频处理和会议查询工具，并将每场已处理会议作为 `meeting://{id}` 资源公开。MCP 客户端通过 stdio 连接。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "uladzkha-samuraizer": {
      "command": "npx",
      "args": [
        "-y",
        "@samuraizer/mcp-server"
      ],
      "env": {
        "SAMURAIZER_MEETINGS_DIR": "<SAMURAIZER_MEETINGS_DIR>"
      }
    }
  }
}

启动命令npx -y @samuraizer/mcp-server

需要配置的环境变量

SAMURAIZER_MEETINGS_DIRDirectory containing processed meetings, overriding meetingsDir from the Samuraizer config file. A config file is still required — run 'samuraizer init' first.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@samuraizer/mcp-server0.1.7stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
inputPath	string	是	源音频文件的绝对路径
outputPath	string	是	输出 WAV 文件的绝对路径

详细介绍

@samuraizer/mcp-server

本地优先的 MCP 服务，让 AI Agent 能够访问你的会议录音——转录文本、摘要、行动事项和决策——而无需将任何内容发送到云端。

适用于 Samuraizer 的 Model Context Protocol 服务，可通过 stdio 向 AI Agent（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 访问的单个已处理会议。

每个工具的完整输入和输出详情请参阅下方的工具。

该服务提供两种模式：

查询模式 — 将先前处理的会议作为结构化数据或 MCP 资源列出并获取。只读，运行时无需大模型或音频依赖项。
处理模式 — 对音频文件运行完整的 Samuraizer 处理流程（规范化 → 转录 → 摘要 → 提取行动事项／决策）。需要与 samuraizer 本身相同的本地工具链：whisper-cli、ffmpeg、ffprobe，以及正在运行的 Ollama 实例。

所有内容都保留在本地。该服务会从你机器上的目录读取会议内容，绝不会将数据发送到任何外部服务。

前置条件

此软件包依赖 @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 通信。不适合在 shell 中交互式使用——它面向由 Claude Desktop 或 MCP Inspector 等 MCP 客户端启动。

使用 MCP Inspector 检查

npx @modelcontextprotocol/inspector samuraizer-mcp

这会打开一个浏览器界面，你可以在其中列出工具和资源、传入参数调用它们并查看响应，适合用于调试。

从 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

请参阅 Claude Code MCP 文档，了解如何通过命令行管理 MCP 服务。

配置

MCP 服务读取与 @samuraizer/cli 相同的配置文件。服务本身没有单独的配置。

环境变量覆盖

所有配置字段都支持通过环境变量覆盖，适用于在不同环境中运行服务（例如，为每个项目运行一个 MCP 服务）：

变量	对应字段
`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 请求，并且需要有足够的空闲 VRAM 来容纳额外的 KV 缓存槽。

工具

查询模式

`search_meetings`

按摘要文本、会议名称、行动项和决策搜索已处理的会议。

刻意不搜索转录文本——它们比上述字段大 1 到 2 个数量级，每次查询都扫描转录文本无法扩展。需要查看转录文本时，请使用 get_meeting。

输入：

query （string，必填） — 搜索查询，不区分大小写。请参阅查询语法。
limit （integer，可选） — 返回结果的上限（默认值为 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) — 要返回的结果数上限。

返回： 会议摘要的 JSON 数组（id、name、generated_at、summary_preview、participant_count、duration_sec）。

`get_meeting`

获取特定会议的完整处理结果。

输入：

id (string, required) — 会议 ID（ULID）。

返回： 完整的会议 JSON，包括转录文本、摘要、行动项、决策和来源元数据。如果找不到该会议，则返回错误。

处理模式

这些工具会按需运行 Samuraizer 工作流的部分环节。它们依赖本地运行时（whisper-cli、ffmpeg、Ollama）。

`process_recording`

对音频文件运行完整工作流。通过 Agent 处理录音时，推荐使用此入口。

输入：

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 scheme： meeting://{id}
MIME 类型： application/json
内容： 完整的会议 JSON，与 get_meeting 返回的内容相同。

列出资源时，会为 meetingsDir 中的每场会议返回一个条目。读取资源时，会返回其完整内容。对于会在界面中展示资源的客户端（例如 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 显示服务未连接

常见原因：

Claude Desktop 无法在其看到的 PATH 中找到 samuraizer-mcp。请使用绝对路径。
配置文件不是有效的 JSON。请使用 jq . < claude_desktop_config.json 验证。
服务因缺少配置文件或配置无效而在启动时崩溃——请检查 Claude Desktop 的 MCP 日志。

许可证

MIT——参见 LICENSE。

源代码

github.com/UladzKha/samuraizer-cli（monorepo）

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Samuraizer

关于 Samuraizer

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

@samuraizer/mcp-server

工具一览

前置条件

安装

使用方法

直接运行服务

使用 MCP Inspector 检查

从 Claude Desktop 连接

从 Claude Code 连接

配置

环境变量覆盖

工具

查询模式

search_meetings

查询语法

list_meetings

get_meeting

处理模式

process_recording

normalize_audio

transcribe_audio

summarize_transcript

extract_action_items

extract_decisions

资源

会议输出格式

故障排除

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

服务启动，但 list_meetings 返回空数组

启动服务时出现 EACCES

Claude Desktop 显示服务未连接

许可证

源代码

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

`search_meetings`

`list_meetings`

`get_meeting`

`process_recording`

`normalize_audio`

`transcribe_audio`

`summarize_transcript`

`extract_action_items`

`extract_decisions`

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

服务启动，但 `list_meetings` 返回空数组

启动服务时出现 `EACCES`