docbase

docbase

docbase は、エージェントやターミナルを使うユーザーに、MongoDB データベースツール一式を提供します。データベースやコレクションの参照、find クエリや集計パイプラインの実行、ドキュメントの挿入・更新・削除、インデックスやコレクションの管理、データベース統計やサーバーログの読み取り、クエリプランの説明要求ができます。

MongoDB ドライバーは同梱されていません。各ツール呼び出しは、まず通常の MongoDB コマンドドキュメント（{ find: ... }、{ aggregate: ... }、{ createIndexes: ... }）に変換され、デフォルトの実行器が mongosh コマンドラインクライアントを使って db.runCommand(...) 経由でそのドキュメントを実行します。そのため、リアルタイムの応答を必要とするマシンでは、mongosh が PATH 上にあり、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. 実行器がドキュメントを実行します。3 つのツールは応答を後処理します。collection-schema は 25 件のドキュメントをサンプリング（$sample）し、そこからフィールドと型の対応表を推定します。mongodb-logs は getLog を実行し、返された行に要求された limit を適用します。export は find を実行し、該当するドキュメントを要求されたエクスポートタイトルのもとで返します。

MCP サーバー

1 つのバイナリで、どちらの形式にも対応します。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 を参照してください。