mcp-approval-queue

@opafex/mcp-approval-queue

MCP サーバーとして動作する、AI エージェント向けのヒューマン・イン・ザ・ループ承認ゲートです。

エージェントは、リスクのある操作を行う前に request_approval を呼び出します。操作のリスクがスコア化され、設定したルールで対象にならない場合は、MCP クライアントに表示されるフォーム（MCP elicitation）またはターミナルから、人間が判断します。エージェントには、実行の可否を示す proceed: true|false が返されます。

エージェントは申請できますが、承認できるのは人間だけです。 モデルが呼び出せる承認、却下、ルール追加のツールはありません。制御対象のエージェント自身が開ける承認ゲートは、ゲートとは言えません。

Node.js 20+ が必要です。

クイックスタート

クライアントの MCP 設定に追加します（Claude Code の場合、プロジェクトのルートにある .mcp.json）。

{
  "mcpServers": {
    "approval-queue": {
      "command": "npx",
      "args": ["-y", "@opafex/mcp-approval-queue"]
    }
  }
}

次に、たとえばプロジェクトの指示で、エージェントに使用するタイミングを伝えます。

データの削除、メールの送信、金銭の支出、デプロイを行う前に request_approval を呼び出し、proceed が true の場合にのみ続行してください。

リクエストの判断方法

1. リスクはアクション名からスコア化されます。bulk_delete_users のように、単語の位置にかかわらず「delete」が含まれていれば削除として扱われます。また、params.estimatedCost も考慮されます。エージェントは category を渡せますが、リスクスコアを引き上げることしかできず、引き下げることはできません。

2. ルールによって自動承認される場合があります。対象は低リスクまたは中リスクに限られ、人間が作成したルールのみが適用されます。高リスクと重大リスクは、必ず人間の判断を仰ぎます。

3. それ以外の場合は、人間が判断します。

   • クライアントで判断する場合 — クライアントが elicitation に対応していれば、サーバーはアクション、リスク、パラメーター、エージェントの理由を示して直接確認し、回答を待ちます。回答はモデルではなくサーバーに送られます。承認、却下、または Always approve にチェックを入れてルールを作成します（低リスク／中リスクのみ）。フォームを閉じた場合、リクエストは保留のままです。

   • ターミナルで判断する場合 — それ以外の場合、リクエストは保留になり、エージェントには check_status をポーリングするよう伝えられます。

     npx @opafex/mcp-approval-queue pending
     npx @opafex/mcp-approval-queue approve appr_3f9c1a2b4d5e --reason "checked the recipient list"
     npx @opafex/mcp-approval-queue reject  appr_3f9c1a2b4d5e
     

4. 未回答のリクエストは 24 時間後（APPROVAL_QUEUE_TTL_HOURS）に期限切れとなり、承認できなくなります。

却下されずに同じアクションが人間に5回承認されると、次のフォームで always approve が提案されます。自動承認はこの回数に含まれません。システムが自分自身に同意しても、証拠にはなりません。

ツール（エージェントに表示されるもの）

ツール	説明
request_approval	アクション（action、任意の params、context、category、wait）を申請します。status、proceed、リスク、次に行うことを返します。
check_status	id を指定してリクエストの状態を再確認します。
list_pending	人間の判断待ちリクエストを、新しいものから順に一覧表示します。
list_rules	人間が設定した自動承認ルールを読み取り専用で表示します。

status は pending、approved、rejected、auto_approved、expired のいずれかです。proceed が true の場合にのみ続行してください。

リソース

URI	内容
approval://stats	ステータス別の件数と、人間が判断に要した平均時間
approval://rules	現在の自動承認ルール
approval://history	直近50件の判断

CLI

mcp-approval-queue                       start the MCP server (stdio)
mcp-approval-queue pending               list requests waiting for a decision
mcp-approval-queue show <id>             one request in full
mcp-approval-queue approve <id> [--always] [--reason <text>]
mcp-approval-queue reject <id> [--reason <text>]
mcp-approval-queue rules                 list rules
mcp-approval-queue rules add <pattern> --max-risk <low|medium> [--description <text>]
mcp-approval-queue rules remove <id>
mcp-approval-queue history [limit]

パターンにはグロブを使います。* は任意の文字列、? は任意の1文字に一致し、大文字と小文字は区別されません。高リスクや重大リスクを対象にするルールは作成できません。

設定

変数	デフォルト	説明
APPROVAL_QUEUE_STATE_DIR	~/.opafex/approval-queue	state.json（リクエスト、ルール、履歴）の保存場所です。サーバーと CLI は同じディレクトリを指定する必要があります。
APPROVAL_QUEUE_TTL_HOURS	24	判断されないリクエストが期限切れになるまでの時間

状態は1つの JSON ファイルに保存され、ロックファイルを使ってアトミックに書き込まれるため、サーバーと CLI を同時に実行できます。

保護されないもの

このツールに依存する前に、次の点を明確に理解してください。

• シェルやファイルにアクセスできるエージェントは、ターミナルチャネルを利用できます。 CLI と state.json が人間専用のチャネルとなるのは、エージェントがコマンドを実行したりファイルを書き込んだりできない場合に限られます。Claude Code などのコーディングエージェントは、通常これらの操作ができます。そのような環境では、エリシテーションチャネルを利用し、クライアントの権限設定でエージェントによる CLI と state ディレクトリへのアクセスを拒否してください。Claude Code の場合は、Bash(npx @opafex/mcp-approval-queue approve:*)、Bash(npx @opafex/mcp-approval-queue rules:*)、および ~/.opafex/ 内の編集を拒否してください。
• エージェントが確認を求めた内容のみを制御します。 エージェントは request_approval を呼び出し、proceed: false を尊重する必要があります。これは協調的なエージェントを対象としたプロトコルであり、許可された内容の記録であって、サンドボックスではありません。強制する必要がある操作には、クライアント独自のツール権限と併用してください。
• エリシテーションを表示するのはクライアントです。 回答が人間からのものであるという保証は、クライアントがフォームをどのように表示するかに左右されます。

ライブラリとしての使用

import { ApprovalQueueService, StateStore, assessRisk } from '@opafex/mcp-approval-queue';

const queue = new ApprovalQueueService(new StateStore('/var/lib/my-app/approvals'));
const { request } = await queue.requestApproval({ action: 'refund_order', params: { estimatedCost: 40 } });

開発

npm install
npm run build
npm test

ライセンス

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