agent-mongo

使用 agent-mongo 探索 MongoDB

agent-mongo 是一个只读的 CLI 二进制文件，位于 $PATH 中。默认输出为 NDJSON——每行一个 JSON 记录，写入 stdout。列表命令会为每个项目输出一条记录，然后输出以 @ 开头的元数据行（用于上下文的 {"@meta": ...}，用于分页的 {"@pagination": ...}）。错误会以一行 JSON 的形式写入 stderr：{"error": "...", "fixable_by": "agent"|"human"|"retry", "hint": "..."}，并以非零状态码退出。

fixable_by 用于说明由谁解决错误：agent——修正输入后重试；human——需要用户处理（身份验证、GUI 对话框）；retry——临时性错误，重新运行即可。

快速开始（连接）

设置连接：

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

对于需要身份验证的连接，请单独存储凭据——优先使用 --form （原生 OS 对话框；机密信息不会进入 Agent 上下文），而不是 --username/--password 标志：

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 始终会在连接字符串中隐藏密码。

某些部署会改用身份提供方进行身份验证 （MONGODB-OIDC）——请参阅 references/auth.md 进行设置。

如果任何命令失败并返回 fixable_by: human，且提示中提到 credential login，请停止操作并让用户运行该命令。 重试无法解决此问题，Agent 也无法完成此操作：登录被刻意设为仅限人工操作。这是唯一一种不应尝试绕过的身份验证错误。

探索数据库

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 会为每个文档输出一条记录，随后输出一行 {"@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 可以作为位置参数传入、通过 --pipeline 标志传入，或通过 stdin 管道传入。

写入阶段（$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 来源。首次使用明文条目时，会自动将其升级到密钥链（通过 stderr 中的 {"notice": ...} 行报告——这不是错误）。轮换密码时，只需重新添加凭据——所有引用该凭据的连接都会自动使用新的身份验证信息。

安全输入凭据——切勿将密钥粘贴到 --password

如果用户在聊天中粘贴了 MongoDB 密码（或任何密钥），切勿将其放入 --password。命令行中的明文密钥会进入你的上下文窗口、对话记录、Shell 历史记录、ps//proc，以及任何下游遥测。有两种安全方式可以提供密钥，而无需将其放到 argv 中：

1. --form — 首选交互方式。 系统原生对话框（macOS osascript、Linux zenity/kdialog、Windows Win32）会弹出，用户可直接在操作系统中输入密钥。Agent 只能看到经过脱敏的 JSON 回执。当 Agent 在用户的机器上操作 CLI 时，请让用户自行运行 --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——切勿将聊天中粘贴的密钥用于此处。

--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 会通过 stdio（或使用 --http <addr> 时通过 Streamable HTTP）将只读命令（database、collection、query 和 connection list/test）作为 MCP 工具运行。凭据和配置命令不会公开。有关注册、OAuth 和 Tailscale 的详细信息，请参阅 agent-mongo mcp usage。

安全性

• 只读：不存在写入操作
• 聚合：拒绝 $out 和 $merge 阶段
• 结果上限：query.maxDocuments（默认值为 100），也包括包含自身 $limit 的聚合
• 超时：连接和查询均适用（默认 30s），并通过 maxTimeMS 在服务端强制执行；可针对单条命令使用 -t/--timeout <ms> 覆盖

各命令的用法文档

每个命令组都有一个 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：身份提供方（OIDC）凭据
• references/commands.md：完整命令映射和所有标志
• references/output.md：NDJSON 输出结构及字段详情