gateway

@recordist/gateway

Recordist（https://recordist.app）用の MCP サーバー＋A2A エージェントです。Recordist は、通話にボットを参加させずに、自分のノートパソコン上で通話のメモを作成するアプリです。Claude Desktop、Claude Code、Cursor などのエージェントから、ノートパソコンで録音したミーティングを読み取り、操作できます。

Mac 用の Recordist アプリを無料で入手できます。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 はただちに録音を開始します。それ以外の場合、Chrome 拡張機能や Stream Deck と同様に、Recordist がノートパソコン上に専用の録音カードを表示し、ユーザーが応答するまで録音は始まりません。Recordist 1.0.4 以前では、Settings の Detection で Chrome 拡張機能のスイッチがオンの場合にのみ、そのカードが表示されます。両方がオフの場合、エージェントには録音が開始されなかったことが通知され、ユーザーは 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

または、npx -y @recordist/gateway --http の実行中に 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 エージェント（--a2a）は、 Authorization: Bearer <api_token> を含むリクエストにのみ応答します。トークンは <data>/api_token の内容（または RECORDIST_API_TOKEN）で、ゲートウェイが アプリのローカル API に使用するものと同じです。トークンがない、または誤っている場合は、 WWW-Authenticate: Bearer を含む 401 だけが返されます。例外は A2A Agent Card で、クライアントが認証方式を確認できるよう公開されています。スキルのみが記載され、 ミーティングは記載されません。トークンがない場合、どちらのモードも起動せず、 stdio を含む --all も起動しません。Recordist を一度開いて api_token を書き込ませるか、 フラグを指定せずに実行して stdio のみを使用してください。stdio トランスポートでは、 起動したアシスタントだけが接続できるため、トークンは不要です。--doctor では、 --http と --a2a にトークンが必要か、起動が拒否されるかを確認できます。

アシスタントが利用できるもの

ツール

ツール	用途
list_meetings	最近のミーティング。q、from／to、limit／offset を指定できます
get_meeting	メモ、アクションアイテム、マーカーを含む1件のミーティング
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 の「以前のメモ」に保存されます（破壊的操作）。アプリが必要です
start_recording	録音を開始します。エージェントによる録音開始を許可がオンの場合（「設定」→「連携」、既定ではオフ）はすぐに開始し、そうでない場合は本人が回答するための Recordist の録音カードを表示します。アプリが必要です
stop_recording	進行中の録音を停止します（破壊的操作：ホストに事前確認します）。アプリが必要です
add_marker	現在の時点にブックマークを追加します。アプリが必要です
propose_action	Recordist Agent：録音に対するアクションを提案します（フォローアップを下書きする、約束を完了としてマークする、ミーティングをエクスポートするなど）。実行はされません。アプリに実行内容を正確に示すカードが表示され、本人が「承認」または「今はしない」を選ぶまで待機します。アプリと、「設定」→「連携」→「Recordist Agent」の接続済みアシスタントによるアクションの提案を許可が必要です
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 エージェント

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 パートを返します。ルーターを使わない場合は、 {"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 として実行できます。

--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 用のベアラートークン、および呼び出し元に必要な --http と --a2a 用のトークン

バックエンド選択の仕組み

呼び出しごとに、ゲートウェイは GET /v1/health を確認します（タイムアウトは 800 ms、結果は 5 秒間キャッシュされます）。アプリが応答した場合、呼び出しは 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 エージェントは自身の Host のみを受け付け、許可リストに登録されていないブラウザー Origin は受け付けません。また、JSON-RPC POST は application/json のみを受け付けます。
• ゲートウェイ自体が通信するのは、127.0.0.1 上の Recordist アプリのみです。ゲートウェイが返すデータは、接続先の AI アシスタントに渡されます。そのアシスタントが自身のクラウドモデルに送信する可能性があるため、会議データを安心して預けられるアシスタントだけを接続してください。
• --http と --a2a では、すべてのリクエストに Authorization: Bearer <api_token> が必要です（A2A Agent Card は除きます）。トークンは一定時間比較されるため、マシン上のほかのユーザーアカウントがこれらを通じて会議データを読み取ることはできません。ご自身のアカウントで実行されているプログラムは api_token を読み取れるため、このトークンによってそれらとご自身を分離することはできません。
• API トークンは <data>/api_token から読み取られます。このファイルはアプリによってモード 0600 で書き込まれます。--doctor は、ファイルがグループまたは全ユーザーから読み取り可能な場合に警告します。決してコミットしたり共有したりしないでください。このトークンを持つ人は、ノート PC 上の録音を操作できます。
• SQLite データベースは読み取り専用で開かれます。ゲートウェイがデータベースを変更することはありません。
• テレメトリーはありません。ゲートウェイがネットワーク通信を行うのは、Recordist アプリのローカル API に対してのみです。

プライバシー

ゲートウェイと拡張機能が通信するのは、ノート PC 上の 127.0.0.1 で動作する Recordist アプリのみで、それ以外とは通信しません。Recordist にデータを送信することはなく、テレメトリーもありません。ツールが返すデータは、呼び出したアシスタントに渡されます。そのアシスタントは、プロバイダーの利用条件に基づいて自身のクラウドモデルに送信する可能性があります。 Recordist のプライバシーポリシー：https://recordist.app/privacy

Claude Desktop Extension

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、および recordist-<version>.mcpb をビルドする scripts/build-mcpb.sh。
• .claude-plugin/marketplace.json でマーケットプレイスに登録されている、 plugins/recordist の Claude Code プラグイン。
• アプリを閉じた状態での読み込みでは、better-sqlite3 を読み込めない場合に node:sqlite にフォールバックします。たとえば、ビルドに使用したものとは 異なる Node で実行した場合です。どちらでも recordist.db を開けない場合は、 ファイルが見つからないとだけ表示せず、それぞれの理由をエラーに表示します。
• 0.1.7 のセットアップはそのまま動作します。トランスポート、トークンチェック、 ツール名に変更はありません。
• エージェントによる録音の開始を許可 がオフ（デフォルト）の場合でも、 start_recording がただ失敗することはなくなりました。Recordist に専用の 録音カードを表示するよう依頼し、ユーザーが応答するまで録音は始まらないことを 伝えます。安全なデフォルト設定でも「この通話を録音」が使えるようになりました。
• 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 アシスタントに送られ、AI アシスタントから独自のクラウドモデルへ送信される 場合があります。以前のバージョンでは、データがマシンの外に出ることはないと 記載していました。それはゲートウェイ単体については正しいですが、クラウドの アシスタントは読み取った内容をプロバイダーに送信します。
• README に、ゲートウェイはデフォルトで 127.0.0.1 にバインドされ、 --host はコンテナー用であることを記載しました。以前は、ゲートウェイは 常に 127.0.0.1 にのみバインドされると記載していました。
• Recordist アプリは、公開されているビルドが唯一のものである Apple silicon 搭載 Mac 向けに提供されていると説明しています。
• start_recording では、アプリ上の設定名に合わせて、設定を エージェントによる録音の開始を許可 と表記します（設定 → インテグレーション）。
• 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 エージェントでは 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 サーバーにはベアラートークンが必要で、指定されていない場合はエラーをスローします。

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 が制作しました。