docbase

docbase

docbase 为 Agent（或在终端操作的你）提供一整套 MongoDB 数据库工具：浏览数据库和集合、运行 find 查询和聚合管道、插入、更新和删除文档、管理索引和集合、读取数据库统计信息和服务日志，并让服务解释查询计划。

它不内置 MongoDB 驱动。每次工具调用都会先映射为普通的 MongoDB 命令文档（{ find: ... }、{ aggregate: ... }、{ createIndexes: ... }），默认执行器则通过 mongosh 命令行客户端运行该文档，并调用 db.runCommand(...)。因此，需要获取实时结果的机器必须在 PATH 中配置 mongosh，并能连接到 MongoDB 实例。缺少其中任一条件时，服务仍会启动并列出工具；只有在实际调用时才会以通俗语言报告问题。

安装

npx @reneturcios/docbase call list-databases

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/docbase

容器默认启动 MCP 服务（见下文）。请注意，标准镜像未捆绑 mongosh 二进制文件，因此容器中的实时查询需要使用主机提供的 mongosh，或将其挂载到镜像中。

CLI

# Run one tool; the JSON-args argument is optional for no-arg tools
docbase call list-databases
docbase call find '{"database":"shop","collection":"users","filter":{"active":true},"limit":5}'
docbase call db-stats '{"database":"shop"}'

# Start the MCP server (connection string optional, see below)
docbase mcp mongodb://alice@localhost:27017/shop

docbase --version

退出代码：成功时为 0；工具调用、连接或 mongosh 本身失败时为 1（错误消息会说明具体原因）；用法错误时为 2。

连接字符串是标准的 MongoDB URL（mongodb:// 或 mongodb+srv://）。对于 mcp 和 call，可以不在命令行中提供连接字符串，而改用 MDB_MCP_CONNECTION_STRING 环境变量。connect 工具还接受 connectionString 参数，该参数会经过验证，并用于本次调用的 ping。

调用流程

1. 验证参数（必需的数据库／集合名称、对象类型的筛选条件、非空文档数组等）。无效调用会在到达执行器之前失败。
2. 将调用映射为命令文档。例如，update-many 会转换为 { update: <collection>, updates: [{ q: filter, u: update, multi: true }] }。
3. 执行器运行该文档。三个工具会对回复进行后处理：collection-schema 会对 25 个文档进行采样（$sample），并据此推断字段到类型的映射；mongodb-logs 会运行 getLog，并对返回的行应用指定的 limit；export 会运行 find，并以指定的导出标题返回匹配的文档。

MCP 服务

一个可执行文件同时提供两种入口。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/docbase mcp mongodb://alice@localhost:27017/shop

MCP 客户端配置：

{
  "mcpServers": {
    "docbase": {
      "command": "npx",
      "args": ["-y", "@reneturcios/docbase", "mcp"],
      "env": { "MDB_MCP_CONNECTION_STRING": "mongodb://alice@localhost:27017/shop" }
    }
  }
}

工具

工具	必需	可选	功能
connect	—	connectionString	Ping 实例（验证提供的连接字符串）
list-databases	—	—	列出所有数据库（listDatabases）
list-collections	database	—	列出数据库中的集合
collection-schema	database、collection	—	根据 25 个文档的样本推断字段类型
collection-indexes	database、collection	—	列出集合的索引
collection-storage-size	database、collection	—	集合存储统计信息（collStats）
find	database、collection	filter、projection、limit、sort	执行 find 查询
aggregate	database、collection、pipeline	—	执行聚合管道
count	database、collection	query	统计匹配的文档数
insert-many	database、collection、documents	—	插入文档（按顺序）
update-many	database、collection、filter、update	—	更新所有匹配的文档
delete-many	database、collection、filter	—	删除所有匹配的文档
create-collection	database、collection	—	创建集合
drop-collection	database、collection	—	删除集合
drop-database	database	—	删除数据库
rename-collection	database、collection、newName	—	重命名集合（在同一数据库中）
create-index	database、collection、keys	—	创建索引；索引名称根据键生成
drop-index	database、collection、indexName	—	按名称删除索引
explain	database、collection	method、methodArgs	解释查询计划（queryPlanner 详细程度）
export	database、collection	exportTitle、filter	在导出标题下返回匹配的文档
db-stats	database	—	数据库统计信息（dbStats）
mongodb-logs	—	limit、type	读取服务日志行（getLog，默认为 global）

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live database
npm run dev     # run the CLI from source via tsx

所有命令构造、验证、架构推断和日志限制功能都由测试覆盖。测试通过虚拟执行器驱动核心逻辑，无需 MongoDB 服务或 mongosh 二进制文件即可运行测试套件。

许可证

MIT — 参见 LICENSE。