Archery MCP 2FA

@seaxlab/archery-mcp に Archery TOTP 二要素認証（2FA）サポートを追加する永続パッチ。

このプロジェクトはデータベースに直接接続せず、Archery の権限、マスキング、レート制限、監査メカニズムを迂回することもありません。ログインフローを拡張して、TOTP を有効にした Archery アカウントでも MCP サービスを通じて認証を完了できるようにするだけです。

現在のパッチは @seaxlab/archery-mcp@3.0.2 にのみ適用されます。アップストリームの依存関係をアップグレードする前に、パッチが引き続き互換性があることを確認し、パッチファイルを再生成してください。

機能

• 起動時に設定内の Archery アカウントとパスワードで自動ログインします。

• TOTP 認証が検出された場合、対話型ターミナルで 6 桁の認証コードの入力を求めます。

• 対話型ターミナルがない場合は、MCP ツールで認証を完了します。

• 認証成功後、同じ Archery セッションを再利用します。

• TOTP 認証コードは現在のリクエストにのみ使用され、設定ファイルやメタデータキャッシュには書き込まれません。

• patch-package を使用して、依存関係のインストール後にパッチを自動適用します。

Related MCP server: auth-vault

環境要件

• Node.js 24 以降。

• npm 10 以降。

• アクセス可能な Archery サービス。アップストリームパッケージは Archery v1.8.5 をサポートしています。

• TOTP が有効な Archery アカウント、または通常のアカウントとパスワード。

クイックスタート

1. プロジェクトを取得して依存関係をインストールする

git clone <repository-url>
cd archery-mcp-2fa
npm ci

npm ci が完了すると、postinstall スクリプトが patches/ 内の 2FA パッチを自動的に適用します。

2. 設定ファイルの準備

アップストリームパッケージが提供するサンプルを基に設定を作成できます：

mkdir -p ~/.config/archery-mcp
cp node_modules/@seaxlab/archery-mcp/config.example.toml \
  ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

~/.config/archery-mcp/pro.toml を編集し、少なくとも以下を記入します：

env = "pro"

[server]
host = "127.0.0.1"
port = 3000

[archery]
base_url = "https://archery.example.com"
username = "mcp_service"
password = "replace-with-a-strong-password"

[query]
default_limit = 100
max_limit = 500

[cache]
enabled = true
ttl_seconds = 604800
exclude_instance_names = []
exclude_instance_ids = []

設定ファイルには平文のパスワードが含まれます。常にファイルの権限を制限し、実際の設定をリポジトリにコミットしないでください。

完全な設定項目の説明は、アップストリームプロジェクトのインストール後の node_modules/@seaxlab/archery-mcp/README.md と config.example.toml を参照してください。

3. サービスの起動

コマンドライン引数で設定ファイルを指定します：

npm start -- --config ~/.config/archery-mcp/pro.toml

環境変数を使用することもできます：

ARCHERY_MCP_CONFIG=~/.config/archery-mcp/pro.toml npm start

デフォルトの MCP アドレスは次のとおりです：

http://127.0.0.1:3000/mcp

ヘルスチェックアドレスは次のとおりです：

http://127.0.0.1:3000/health

TOTP 認証フロー

対話型ターミナル

アカウントで TOTP が有効になっている場合、起動時にターミナルで次のように求められます：

archery-mcp [env=pro] Archery requires TOTP authentication
请输入当前 6 位 TOTP 验证码:

認証アプリに現在表示されている認証コードを入力します。認証が成功すると、サービスはポートのリッスンを開始します：

archery-mcp [env=pro] TOTP authentication succeeded
archery-mcp [env=pro] listening on http://127.0.0.1:3000/mcp

認証コードが無効な場合は、そのまま再試行できます。Archery セッションが期限切れになるか、プロセスが再起動された場合は、再認証が必要です。

対話型ターミナルがない場合

サービスがコンテナ、バックグラウンドタスク、プロセスマネージャーによって起動され、対話型ターミナルがない場合でも、サービスは起動し、次の MCP ツールを登録します：

認証手順：

1. archery_auth_status を呼び出します。

2. two_factor_required: true が返された場合は、ユーザーに認証アプリに現在表示されている 6 桁の認証コードを提供してもらいます。

3. archery_submit_otp を { "otp": "123456" } のパラメータで呼び出します。

4. authenticated: true が返されたことを確認してから、クエリまたは SQL 監査ツールを呼び出します。

上記の 2 つの認証ツール以外の MCP ツールは、アップストリームの @seaxlab/archery-mcp と同じです。

MCP クライアント設定

Streamable HTTP をサポートする MCP クライアントを使用して接続します：

{
  "mcpServers": {
    "archery": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Codex は ~/.codex/config.toml で設定できます：

[mcp_servers.archery]
url = "http://127.0.0.1:3000/mcp"

Claude Code はコマンドラインで追加できます：

claude mcp add --transport http archery http://127.0.0.1:3000/mcp

プロジェクト構造

.
├── patches/
│   └── @seaxlab+archery-mcp+3.0.2.patch  # TOTP 支持补丁
├── package.json                           # 依赖和启动脚本
├── package-lock.json                      # 锁定依赖版本
└── README.md

よく使うコマンド

npx -y @seaxlab/archery-mcp@3.0.2 を直接使用して起動しないでください。実行されるのは、このプロジェクトの 2FA パッチを含まない公式 npm パッケージです。

セキュリティについて

• デフォルトでは 127.0.0.1 のみをリッスンします。MCP HTTP エンドポイント自体には認証がないため、パブリックネットワークに直接公開しないでください。

• マシンをまたいでアクセスする場合は、リバースプロキシ層で TLS、アクセス認証、ネットワークアクセス制御を追加してください。

• Archery パスワードは TOML 設定に保存されます。chmod 600 を設定し、専用の最小権限サービスアカウントを使用してください。

• 実際のパスワード、TOTP 認証コード、セッション Cookie、内部 Archery アドレス、本番設定をリポジトリ、Issue、ログにコミットしないでください。

• TOTP は MCP リクエストを介して渡されます。リモート MCP クライアントを使用する場合は、通信経路が信頼でき、暗号化されていることを確認してください。

互換性とメンテナンス

パッチはアップストリームパッケージのビルド成果物に直接作用するため、アップストリームのバージョンが変わると、パッチが適用できなくなったり、動作が非互換になったりする可能性があります。アップグレード時には以下を推奨します：

1. package.json 内の @seaxlab/archery-mcp のバージョンを更新します。

2. npm install を実行し、パッチの競合を確認します。

3. node_modules/@seaxlab/archery-mcp で 2FA の変更を再実装し、検証します。

4. npx patch-package @seaxlab/archery-mcp を実行して新しいパッチを生成します。

5. 対話型ターミナルと対話型ターミナルがない環境の両方で認証フローを検証します。

貢献

Issue または Pull Request を歓迎します。コードを提出する前に、実際のアカウント、パスワード、認証コード、Cookie、内部ドメイン名、その他の機密情報が含まれていないことを確認してください。

謝辞と声明

このプロジェクトは @seaxlab/archery-mcp の公開リリースパッケージに基づいてパッチを作成したものであり、Archery またはアップストリームパッケージ保守者の公式プロジェクトではありません。Archery および関連名称の権利は、それぞれの所有者に帰属します。