agent-mongo

agent-mongo を使った MongoDB の探索

agent-mongo は、$PATH 上で利用できる読み取り専用の CLI バイナリです。デフォルトの出力形式は NDJSON で、標準出力に 1 行につき 1 つの JSON レコードが出力されます。リストコマンドは項目ごとに 1 つのレコードを出力し、その後に @ で始まるメタデータ行（コンテキスト用の {"@meta": ...}、ページング用の {"@pagination": ...}）を出力します。エラーは標準エラー出力に 1 行の JSON {"error": "...", "fixable_by": "agent"|"human"|"retry", "hint": "..."} として出力され、終了コードは 0 以外になります。

fixable_by は、エラーを誰が解決するかを示します。agent は入力を修正して再試行、human はユーザーによる対応（認証や GUI ダイアログなど）が必要、retry は一時的なエラーなので再実行します。

クイックスタート（接続）

接続を設定します。

agent-mongo connection add local "mongodb://localhost:27017/myapp" --default
agent-mongo connection test

認証が必要な接続では、認証情報を別に保存します。--username／--password フラグよりも --form （ネイティブ OS ダイアログ。シークレットがエージェントのコンテキストに入ることはありません）を 優先してください。

agent-mongo credential add acme --form
agent-mongo connection add prod "mongodb+srv://cluster.example.net/myapp" --credential acme --default

URI に埋め込まれた user:pass は自動的に抽出され、接続エイリアスと同じ名前の保存済み認証情報として登録されます（--credential との併用はエラーになります）。そのエイリアスの認証情報がすでに存在し、値が異なる場合、追加は拒否されます。エラーのヒントに従ってください（credential add --form でローテーションするか、既存の認証情報を --credential で指定します）。connection list は、接続文字列内のパスワードを常に伏字にします。

一部のデプロイ環境では、代わりに ID プロバイダー（MONGODB-OIDC）を使って認証します。設定方法については、references/auth.md を参照してください。

コマンドが fixable_by: human を返し、credential login が指定されている場合は、そこで停止してユーザーに実行を依頼してください。 再試行しても解決せず、エージェントが完了することもできません。ログインは意図的に人間のみが実行できるようになっています。回避すべき不具合ではない認証エラーは、これだけです。

データベースを探索する

agent-mongo database list                                # all databases with sizes
agent-mongo collection list myapp                        # all collections in myapp
agent-mongo collection schema myapp users                # infer schema from samples
agent-mongo collection schema myapp users --depth 2      # limit nesting depth
agent-mongo collection schema myapp events --limit 50    # paginate large schemas
agent-mongo collection schema myapp events --limit 50 --skip 50  # next page
agent-mongo collection indexes myapp users               # index key patterns (verbatim specs)
agent-mongo collection stats myapp orders                # document count, sizes
agent-mongo database stats myapp                         # database-level statistics

ドキュメントをクエリする

agent-mongo query find myapp users --filter '{"age":{"$gte":21}}' --limit 10
agent-mongo query find myapp orders --sort '{"createdAt":-1}' --projection '{"status":1,"total":1}'
agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e      # by _id (auto-detects ObjectId)
agent-mongo query get myapp users 665a1b2c3d4e5f6a7b8c9d0e --projection '{"name":1,"email":1}'
agent-mongo query count myapp orders --filter '{"status":"pending"}'
agent-mongo query sample myapp users --size 10                    # random documents
agent-mongo query sample myapp users --size 10 --filter '{"status":"active"}'  # filtered sample
agent-mongo query distinct myapp orders status                    # unique values

query find はドキュメントごとに 1 つのレコードを出力し、その後に {"@pagination": {"has_more": ..., "total_items": ...}} の行を出力します。has_more は、制限数を超えて一致するドキュメントがあることを示し、total_items は一致する件数の合計です。

JSON 引数（--filter、--sort、--projection、--pipeline）は、BSON 型を表す MongoDB Extended JSON を受け付けます。

agent-mongo query find myapp events --filter '{"createdAt":{"$gt":{"$date":"2026-01-01T00:00:00Z"}}}'
agent-mongo query find myapp users --filter '{"_id":{"$oid":"665a1b2c3d4e5f6a7b8c9d0e"}}'

集計

agent-mongo query aggregate myapp orders '[{"$group":{"_id":"$status","count":{"$sum":1}}}]'
agent-mongo query aggregate myapp orders --pipeline '[{"$group":{"_id":"$status","count":{"$sum":1}}}]'
agent-mongo query aggregate myapp events '[{"$match":{"type":"purchase"}},{"$group":{"_id":"$userId","total":{"$sum":"$amount"}}}]'

パイプラインは位置引数、--pipeline フラグ、または標準入力からのパイプで渡せます。

書き込みステージ（$out、$merge）は拒否されます。この CLI は厳密な読み取り専用です。

出力形式

デフォルトは NDJSON（-f jsonl）です。-f/--format で切り替えられます。

agent-mongo database list -f json     # pretty {"data": [...], ...meta} envelope for lists
agent-mongo query count myapp users -f yaml

-f json を指定すると、単一の整形済みエンベロープ（リストの場合は {"data": [...]}、単一結果の場合は整形済みオブジェクトそのもの）が出力されます。出力を自分で読む場合は、NDJSON よりも内容を確認しやすくなります。

接続の管理

agent-mongo connection list                              # saved connections + defaults
agent-mongo connection add staging "mongodb://..." --credential acme
agent-mongo connection update prod --credential new-cred
agent-mongo connection set-default staging
agent-mongo connection remove old-conn
agent-mongo connection test prod                         # verify connectivity (positional alias)
agent-mongo connection test -c prod                      # also works with -c flag

接続の解決順序：-c フラグ > AGENT_MONGO_CONNECTION 環境変数 > 設定のデフォルト値 > 利用可能な接続を一覧表示するエラー。

認証情報の管理

agent-mongo credential add acme --form                   # preferred interactive; see secure entry below
printf '%s' "$PW" | agent-mongo credential add acme --username deploy   # non-interactive machine path
agent-mongo credential list                              # passwords always redacted
agent-mongo credential remove acme --force               # even if connections reference it

認証情報は接続とは別に保存されます。利用可能な場合は OS のシークレットストア（macOS Keychain、Linux Secret Service、Windows Credential Manager）に保存され、利用できない場合は設定ファイルに平文で保存されます。credential list は認証情報ごとに storage の保存元を表示します。平文のエントリは初回使用時にキーチェーンへ自動的に移行されます（標準エラー出力に {"notice": ...} の行が出力されます。これはエラーではありません）。パスワードをローテーションするときは、認証情報を再登録するだけで構いません。その認証情報を参照するすべての接続で、新しい認証情報が自動的に使われます。

認証情報を安全に入力する — --password にシークレットを貼り付けないでください

ユーザーが MongoDB のパスワード（またはその他のシークレット）をチャットに貼り付けた場合、決して --password に指定しないでください。コマンドラインにシークレットを直接指定すると、コンテキストウィンドウ、トランスクリプト、シェルの履歴、ps／/proc、およびあらゆる下流のテレメトリに残ります。シークレットを argv に一度も指定せずに渡す安全な方法は、次の 2 つです。

1. --form — 推奨される対話形式の方法。 ネイティブ OS ダイアログ（macOS osascript、Linux zenity/kdialog、Windows Win32）が表示され、ユーザーはシークレットを OS に直接入力します。エージェントに表示されるのは、シークレットが伏せられた JSON の受領情報のみです。エージェントがユーザーのマシン上で CLI を操作する場合は、シークレットが LLM に渡らないよう、ユーザー自身に --form コマンドを実行してもらってください。

agent-mongo credential add acme --form                              # both fields prompted
agent-mongo credential add acme --username deploy --form            # only password prompted

2. stdin からのパイプ入力 — 非対話型のマシン向け方法。 スクリプト、CI、または GUI を利用できないヘッドレスホストでは、パスワードを stdin にパイプします。パスワードはストリームから読み取られ、コマンドラインには指定されません。--username はシークレットではないため、フラグのまま指定します。

printf '%s' "$PW" | agent-mongo credential add acme --username deploy

パスワードの優先順位は、--password フラグ > stdin からのパイプ入力 > --form ダイアログです。--form または stdin を優先してください。--password は、すでにシークレットではない値（テスト用フィクスチャ、一時的なローカル DB など）に限って使用し、チャットに貼り付けられたシークレットには決して使用しないでください。

--form が失敗した場合は、fixable_by を含む構造化エラーが返されます。

• human — GUI セッションを利用できません（SSH、ヘッドレスホスト）。ユーザーにローカルマシンで実行してもらうか、上記の stdin からのパイプ入力を使用してください。
• retry — ユーザーがダイアログをキャンセルしました。同じコマンドを再実行するのが適切です。

切り詰め

truncation.maxLength（デフォルトは 200）を超える文字列フィールドは … で切り詰められ、元の長さを示す {field}Length キーが付加されます。

agent-mongo --full query find myapp posts                # expand all fields
agent-mongo --expand description query find myapp posts  # expand specific field

これらはグローバルフラグです。コマンドの前後どちらにも指定できます。

タイムアウト

デフォルトのタイムアウトは 30s です（query.timeout で設定可能）。接続フェーズとクエリフェーズの両方に適用されます。コマンドごとに -t/--timeout <ms> で上書きできます。

agent-mongo --timeout 60000 query find myapp large_collection --filter '{"status":"active"}'
agent-mongo --timeout 120000 collection schema myapp events

サーバーにも同じ制限（maxTimeMS）が送信されるため、タイムアウトしたクエリはサーバー側でも停止し、CLI が処理を諦めた後も実行され続けることはありません。タイムアウト時のエラーヒントでは、タイムアウトを延長するか、インデックスを確認するよう案内されます。

すべてのコマンドには、サーバーログ、プロファイラー、currentOp 用のタグが付けられます。comment はコマンドパス（agent-mongo query find）で、接続の appName は agent-mongo/<version> です（接続文字列で設定されている場合を除く）。

設定

agent-mongo config list-keys                             # all keys with defaults/ranges
agent-mongo config set defaults.limit 50
agent-mongo config get query.timeout
agent-mongo config reset                                 # restore defaults

主な設定項目：defaults.limit（20）、defaults.sampleSize（5）、defaults.schemaSampleSize（100）、query.timeout（30000ms）、query.maxDocuments（100）、truncation.maxLength（200）。

MCP サーバー

agent-mongo mcp は、読み取り専用コマンド（database、collection、query、および connection list／test）を、stdio（または --http <addr> を使用した Streamable HTTP）経由の MCP ツールとして実行します。認証情報および設定に関するコマンドは公開されません。登録、OAuth、Tailscale の詳細については、agent-mongo mcp usage を参照してください。

安全性

• 読み取り専用：書き込み操作はありません
• 集計：$out および $merge ステージは拒否されます
• 結果の上限：query.maxDocuments（デフォルトは 100）。独自の $limit を含む集計も対象です
• タイムアウト：接続とクエリの両方に適用され（デフォルトは 30s）、maxTimeMS によってサーバー側で適用されます。コマンドごとに -t/--timeout <ms> で上書きできます

コマンドごとの使用方法ドキュメント

各コマンドグループには、詳細で LLM 向けに最適化されたドキュメントを表示する usage サブコマンドがあります。

agent-mongo usage                  # top-level overview
agent-mongo connection usage       # connection commands
agent-mongo credential usage       # credential management
agent-mongo database usage          # database commands
agent-mongo collection usage       # collection commands
agent-mongo query usage            # all query commands
agent-mongo config usage           # settings keys, defaults, validation
agent-mongo mcp usage              # MCP server transports and registration

特定のドメインについて操作前に詳しい情報が必要な場合は、agent-mongo <command> usage を使用してください。

リファレンス

• references/auth.md：ID プロバイダー（OIDC）の認証情報
• references/commands.md：全コマンドの一覧とすべてのフラグ
• references/output.md：NDJSON の出力形式とフィールドの詳細