gateway

@recordist/gateway

Recordist 的 MCP 服务 + A2A Agent（https://recordist.app）。Recordist 是一款可在你自己的笔记本电脑上为通话撰写笔记的应用，通话中不会有机器人。它能让 Claude Desktop、Claude Code、Cursor 及其他 Agent 读取和处理笔记本电脑上录制的会议。

获取免费的 Recordist Mac 应用；Windows 和 Linux 版本正在预览中： https://recordist.app/download?from=npm

• 读取（列出、获取、转录、搜索、行动项）无论 Recordist 应用是否正在运行都可用：网关会在应用运行时与其本地 API 通信；应用未运行时，则以只读方式打开 recordist.db。
• 操作（开始和停止录制、添加标记、重新生成笔记）需要应用运行。应用未运行时，这些操作会失败并提示 Recordist app is not running。
• 录制前会先征求同意。 只有在 Recordist 的 Settings → Integrations 中开启 Allow agents to start recordings（默认关闭）时，start_recording 才会立即启动录制。否则，Recordist 会像处理 Chrome 扩展和 Stream Deck 的请求一样，在笔记本电脑上显示自己的录制卡片；只有用户确认后才会开始录制。Recordist 1.0.4 及更早版本只有在 Settings → Detection 中开启 Chrome 扩展开关时才会显示该卡片；如果两项都关闭，Agent 会收到录制未开始的提示，用户可以在 Recordist 中手动开始录制。stop_recording 和 regenerate_notes 被标记为破坏性操作，因此遵循 MCP 提示的助手每次都会先征求确认。
• 会议数据的去向。 网关本身只与 127.0.0.1 上的 Recordist 应用通信，并且默认只在环回地址上监听。返回的数据会发送给你连接的 AI 助手，而该助手可能会将数据发送给自己的云端模型。 regenerate_notes 会让应用使用 Recordist 的 Settings → AI notes 中设置的服务提供商撰写笔记，该服务也可能是云服务。

安装

npx -y @recordist/gateway --doctor     # check data dir, DB, token, app

需要 Node 20+。better-sqlite3 为常见平台提供预构建二进制文件。

连接助手

Claude Desktop：扩展

Recordist 扩展只需一步即可安装到 Claude Desktop，无需配置。双击 recordist-<version>.mcpb（请按照Claude Desktop 扩展中的说明构建），或在 Claude Desktop 中打开 Settings → Extensions → Advanced settings → Install Extension… 并选择该文件。安装前，Claude 会显示该扩展的功能。

Claude Desktop：手动配置

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "recordist": {
      "command": "npx",
      "args": ["-y", "@recordist/gateway"]
    }
  }
}

Claude Code

claude mcp add recordist -- npx -y @recordist/gateway

或者，使用 HTTP 传输（此时 npx -y @recordist/gateway --http 正在运行；它需要应用的 API 令牌，参见身份验证）：

TOKEN="$(cat ~/Library/Application\ Support/app.recordist.desktop/api_token)"
claude mcp add --transport http recordist http://127.0.0.1:47322/mcp \
  --header "Authorization: Bearer $TOKEN"

Claude Code 插件

此仓库也是 Claude Code 插件市场。plugins/recordist 中的插件会启动此网关，并固定使用一个已发布版本，还会添加一项技能，用于根据记录回答问题：

/plugin install recordist --marketplace recordist-app/gateway

对于低于 2.1.275 的 Claude Code 版本，请先添加市场： /plugin marketplace add recordist-app/gateway，然后运行 /plugin install recordist@recordist。

Cursor

项目配置文件 .cursor/mcp.json 或全局配置文件 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "recordist": {
      "command": "npx",
      "args": ["-y", "@recordist/gateway"]
    }
  }
}

任意 Streamable HTTP 客户端

npx -y @recordist/gateway --http          # http://127.0.0.1:47322/mcp

每次请求都要发送 Authorization: Bearer <api_token>。

身份验证

HTTP 传输（--http）和 A2A Agent（--a2a）只响应携带 Authorization: Bearer <api_token> 的请求，其中令牌是 <data>/api_token （或 RECORDIST_API_TOKEN）的内容，与网关用于应用本地 API 的令牌相同。缺少令牌或令牌错误时，会返回 401 和 WWW-Authenticate: Bearer，不包含其他内容。唯一的例外是 A2A Agent Card，它保持公开，以便客户端发现身份验证方案；它只列出技能，不会列出会议。没有可用令牌时，两种模式都不会启动，--all 也一样，包括 stdio：先打开一次 Recordist，使其写入 api_token；或者不带标志运行，仅使用 stdio。stdio 传输无需令牌，因为只有启动它的助手才能与其通信。--doctor 会说明 --http 和 --a2a 是否需要令牌，或会拒绝启动。

助手可用的内容

工具

工具	用途
list_meetings	最近的会议；可选 q、from/to、limit/offset
get_meeting	获取一场会议及其笔记、行动项和标记
get_transcript	获取 json | md | srt | vtt | txt 格式的转录文本
search_meetings	在转录文本和笔记中进行全文搜索（FTS5）
get_action_items	获取行动项，可按 meeting_id / open_only 筛选
regenerate_notes	使用 Recordist 中设置的提供商重新生成 AI 笔记（summary、action_items、decisions 等）；新笔记会替换当前笔记，Recordist 会将被替换的笔记保存在 Earlier notes 下（此操作不可撤销）；需要应用
start_recording	录音：启用 Allow agents to start recordings（Settings → Integrations，默认关闭）时立即开始，否则会显示 Recordist 的录音卡片，供用户确认；需要应用
stop_recording	停止正在进行的录音（此操作不可撤销：主持人会先询问）；需要应用
add_marker	为当前时刻添加书签；需要应用
propose_action	Recordist Agent：建议对录音执行一项操作（起草后续邮件、将承诺标记为已完成、导出会议）。不会执行任何操作：应用会显示一张卡片，准确说明将执行的操作，并等待用户选择 Approve 或 Not now；需要应用，并且需要在 Settings → Integrations → Recordist Agent 中启用 Let connected assistants suggest actions
action_status	查看建议的处理结果：proposed、done、failed、declined 或 expired，仅此而已；需要应用

资源：recordist://meeting/{id}（JSON）和 recordist://meeting/{id}/transcript（Markdown）。资源列表显示 最近 50 场会议。

提示词：summarize_meeting、draft_followup_email、weekly_review。

A2A Agent

npx -y @recordist/gateway --a2a           # http://127.0.0.1:47323/

Agent Card 位于 http://127.0.0.1:47323/.well-known/agent.json（公开，无需 令牌；authentication.schemes 为 ["bearer"]）；技能与上述工具对应。 JSON-RPC 2.0 位于 /，支持 tasks/send、tasks/get、tasks/cancel 和 tasks/sendSubscribe（SSE）；每个 JSON-RPC 请求都需要 Authorization: Bearer <api_token>。

自然语言任务会通过一个简单的关键词路由器分配给相应技能；每个完成的任务都会返回一个 text 部分和一个包含结构化结果的 data 部分。若要跳过路由器，请发送一个 data 部分：{"skill": "...", "args": {...}}。

TOKEN="$(cat ~/Library/Application\ Support/app.recordist.desktop/api_token)"

curl -s http://127.0.0.1:47323/ \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tasks/send",
    "params": {
      "id": "task-1",
      "message": { "role": "user", "parts": [
        { "type": "text", "text": "What are my open action items from this week?" }
      ]}
    }
  }' | jq .result.artifacts[0].parts

# explicit skill call
curl -s http://127.0.0.1:47323/ -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":2,"method":"tasks/send",
  "params":{"message":{"role":"user","parts":[
    {"type":"data","data":{"skill":"get_transcript","args":{"meeting_id":"01J…","format":"srt"}}}
  ]}}}'

# streaming
curl -N http://127.0.0.1:47323/ -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":3,"method":"tasks/sendSubscribe",
  "params":{"message":{"role":"user","parts":[{"type":"text","text":"list my meetings from today"}]}}}'

CLI

npx -y @recordist/gateway                 MCP over stdio (default)
npx -y @recordist/gateway --http          MCP over Streamable HTTP on 127.0.0.1:47322/mcp (bearer token)
npx -y @recordist/gateway --a2a           A2A agent on 127.0.0.1:47323 (bearer token)
npx -y @recordist/gateway --all           stdio + --http + --a2a (exits if there is no token)
npx -y @recordist/gateway --doctor        diagnostics: data dir, DB, token, app reachability, HTTP/A2A auth
npx -y @recordist/gateway --version
  --http-port <n>  --a2a-port <n>  --host <addr>

始终使用 npx 并通过其带作用域的名称 @recordist/gateway 运行。全局安装（npm i -g @recordist/gateway）后，同一命令也会以 recordist-gateway 的名称加入 PATH。

--host 会将 --http 和 --a2a 绑定到另一个地址，供容器使用。 请勿将其暴露在网络接口上：令牌会通过未加密的 HTTP 在网络中传输。

日志写入 stderr；stdout 专供 stdio MCP 传输使用。

环境变量

变量	默认值	用途
RECORDIST_DATA_DIR	macOS ~/Library/Application Support/app.recordist.desktop Windows %APPDATA%\app.recordist.desktop Linux ~/.local/share/app.recordist.desktop	recordist.db 和 api_token 的存放位置
RECORDIST_API_URL	http://127.0.0.1:47321	本地 API 基础 URL
RECORDIST_API_TOKEN	<data>/api_token 的内容	本地 API 的 Bearer 令牌，也是调用方使用 --http 和 --a2a 时必须提供的令牌

后端选择方式

每次调用时，网关都会探测 GET /v1/health（超时为 800 ms，结果缓存 5 s）。如果应用有响应，调用就会转发到 API。否则，读取操作会以只读模式打开 <data>/recordist.db（不会写入应用的 WAL），而操作则会返回 Recordist app is not running。如果原生二进制与运行网关的 Node 匹配，则使用 better-sqlite3 打开数据库；如果不匹配，则使用 node:sqlite（Node 22.13 及更高版本）。如果两者都无法打开数据库，错误信息会分别说明原因。如果存在 FTS5（segments_fts），搜索会使用它；否则会回退到 LIKE。

安全说明

• 网关默认绑定到 127.0.0.1。--host 用于容器；请勿在网络接口上公开它。Streamable HTTP 传输会启用 DNS 重绑定保护，并且只接受其自身的 Host（默认是 127.0.0.1 或 localhost）。A2A Agent 只接受其自身的 Host，不接受未列入允许列表的浏览器 Origin，并且只接受 application/json 格式的 JSON-RPC POST 请求。
• 网关本身只与 127.0.0.1 上的 Recordist 应用通信。它返回的内容会发送给你连接的 AI 助手，而助手可能会将其发送到自己的云端模型，因此请只连接你信任其处理会议内容的助手。
• --http 和 --a2a 要求每个请求都携带 Authorization: Bearer <api_token>（A2A Agent Card 除外），并以恒定时间进行比较，因此机器上的其他用户账户无法通过它们读取会议。以你自己的账户运行的程序可以读取 api_token，因此该令牌无法将它们与你隔离。
• API 令牌从 <data>/api_token 读取，应用会以 0600 模式写入该文件。如果文件可被同组用户或所有用户读取，--doctor 会发出警告。切勿提交或分享该令牌；任何拥有该令牌的人都可以控制你笔记本电脑上的录音。
• SQLite 数据库以只读模式打开；网关不会对其进行修改。
• 不进行遥测。除 Recordist 应用的本地 API 外，网关不会发起任何网络请求。

隐私

网关和扩展只会与你笔记本电脑上 127.0.0.1 的 Recordist 应用通信，不会与其他任何对象通信。它们不会向 Recordist 发送任何内容，也不进行遥测。工具 返回的内容会发送给调用它的助手，而助手可能会根据其提供方的条款将内容发送到自己的云端模型。 Recordist 的隐私政策：https://recordist.app/privacy

Claude Desktop 扩展

mcpb/manifest.json 使用 MCP Bundle 格式描述该扩展。使用以下命令构建：

npm ci
bash scripts/build-mcpb.sh      # build/recordist-<version>.mcpb

该脚本会编译网关，以锁定的版本安装生产依赖，排除 better-sqlite3（因此软件包不包含原生代码），然后使用官方 @anthropic-ai/mcpb CLI 验证并打包。Claude Desktop 使用随附的 Node 运行扩展，因此在 Recordist 关闭时，读取操作会使用 node:sqlite。

0.1.8 版本变更

• Claude Desktop 扩展：mcpb/manifest.json、mcpb/icon.png 和 scripts/build-mcpb.sh，用于构建 recordist-<version>.mcpb。
• 在 plugins/recordist 中新增 Claude Code 插件，并由 .claude-plugin/marketplace.json 中的市场收录。
• 应用关闭时读取数据，如果 better-sqlite3 无法加载（例如运行在其未针对其构建的 Node 版本下），则改用 node:sqlite。如果两者都无法打开 recordist.db，错误信息会分别说明原因，而不是只提示文件未找到。
• 0.1.7 版本的设置可以照常使用：传输方式、令牌检查和工具名称均未改变。
• 当 Allow agents to start recordings 处于关闭状态（默认设置）时，start_recording 不再直接失败：它会要求 Recordist 显示自己的录音卡片，并说明只有用户作出回应后才会开始录音。使用安全默认设置时，“Record this call”现在也能正常工作。
• stop_recording 和 regenerate_notes 带有 destructiveHint，因此宿主会在结束录音或替换笔记前征求确认。
• stop_recording 会等待应用最多 30 秒（应用写入最后一段转录内容后才会响应）；如果没有收到响应，则会再次向应用发出请求：已结束的录音会报告为已停止，而不是错误。
• 使用通俗易懂的错误提示；README 现在指向下载页面，而不再指向已关闭的早期体验候补名单。

0.1.7 版本变更

• 安全性：更新依赖，以修复 @modelcontextprotocol/sdk 及其传递依赖中的安全公告。SDK 最低版本现为 1.31.0，这是首个修复 GHSA-6qxp-vccf-f47h 的版本。工具、传输方式和令牌检查均未改变，因此 0.1.6 版本的设置可以照常使用。

0.1.6 版本变更

• README、软件包说明和插件说明现在会指出会议文本的去向。网关本身只与 127.0.0.1 上的 Recordist 应用通信，并且默认只监听回环地址。网关返回的内容会发送给你连接的 AI 助手，而它可能会将内容发送给自己的云端模型。早期版本曾表示没有任何内容会离开你的设备。这对网关本身而言是事实，但云端助手会将读取到的内容发送给其服务提供商。
• README 现在说明网关默认绑定到 127.0.0.1，并说明 --host 用于容器；之前的说法是网关始终只绑定到 127.0.0.1。
• Recordist 应用现说明适用于搭载 Apple silicon 的 Mac，因为目前只发布了这一版本。
• start_recording 使用应用中显示的设置名称：Allow agents to start recordings，位于 Settings → Integrations。
• README 和 --help 中的所有命令均使用带作用域的名称： npx -y @recordist/gateway。
• 源代码注释现在指向公开的 本地 API 参考。
• 工具、传输方式和令牌检查均未改变，因此 0.1.5 版本的设置可以照常使用。

0.1.5 版本变更

• --http 和 --a2a 现在要求每个请求都携带 Authorization: Bearer <api_token>；缺少令牌或令牌错误时会返回 401。A2A Agent Card 仍公开，现在还会列出 authentication.schemes: ["bearer"]。如果你使用了这两种模式之一，请在客户端中添加此请求头（参见身份验证）。stdio 传输方式未变。
• 如果没有可用令牌（缺少 <data>/api_token 且未设置 RECORDIST_API_TOKEN），--http 和 --a2a 将拒绝启动。--all 也会如此，并且会在 stdio 启动前退出，因此使用 --all 启动网关的助手将无法获得任何内容。没有令牌时，请在不带标志的情况下启动（仅 stdio）。
• 库：createMcpHttpServer 和 createA2AServer 现在需要传入 token 选项（应用的 api_token），缺失或为空时会抛出错误。请传入 loadConfig().apiToken，如库的用法所示。
• --doctor 会报告 --http 和 --a2a 是否需要令牌或会拒绝启动，以及令牌的来源。
• MCP HTTP 传输现在会对无法解析的请求路径返回 400，而不是结束进程（A2A Agent 从 0.1.3 版本起就已如此）。

开发

npm install
npm run build      # tsc → dist/
npm test           # vitest
node dist/cli.js --doctor

库的用法

import { createRecordistData, createMcpServer } from "@recordist/gateway";

const data = createRecordistData();          // API with SQLite fallback
const server = createMcpServer(data);        // McpServer; attach any transport

HTTP 和 A2A 服务需要 Bearer 令牌，缺少令牌时会抛出错误：

import { createMcpHttpServer, createMcpServer, createRecordistData, listen, loadConfig } from "@recordist/gateway";

const config = loadConfig();                 // apiToken: <data>/api_token or RECORDIST_API_TOKEN
if (!config.apiToken) throw new Error("open Recordist once so it writes api_token");
const data = createRecordistData(config);
const http = createMcpHttpServer({
  createServer: () => createMcpServer(data),
  token: config.apiToken,                    // callers must send Authorization: Bearer <token>
});
await listen(http, 47322);

关于

该网关是一个精简、开源的桥梁，连接你的 AI 助手与运行在你自己笔记本电脑上的 Recordist。它不包含应用代码或密钥；只能访问运行它的机器上的本地 API。 问题和咨询：[email protected]。安全问题报告：[email protected] （参见 SECURITY.md）。由 Recordist 制作，这是一家位于加拿大安大略省的小型独立工作室。