litebase

litebase

litebase を使うと、ターミナルから操作したり、MCP サーバーとしてエージェントに渡したりできる SQLite データベースを利用できます。小規模なデータベースを扱う日常的な作業、つまりテーブルの作成、行の追加や変更、データの読み取り、テーブル構造の確認、データから得た知見のメモの記録に対応します。

プロビジョニングは不要で、ネイティブアドオンのコンパイルも必要ありません。ストレージエンジンには Node 自体に組み込まれた SQLite ライブラリ（node:sqlite）を使うため、「データベース」はファイルパスだけで表せます。一時的に使う場合は :memory: を指定できます。

インストール

npx @reneturcios/litebase tables ./data.db

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/litebase

コンテナーはデフォルトで MCP サーバーとして起動します（下記を参照）。CLI として使うには、CLI 引数を渡します。

Node バージョン要件

litebase のエンジンは Node 組み込みの node:sqlite モジュールで、Node 22.5 以降でのみ利用できます。パッケージの engines フィールドが >=20 となっているのは、フリートの標準に合わせているためですが、実際との間に差があります。Node 20 では CLI とサーバーは起動しますが、データベースを開いた時点で Node >= 22.5 の要件を示すエラーが発生します。データを実際に読み書きするには、Node 22.5 以降（Node 24 を推奨）を使用してください。

CLI

# List the user tables in a database file
litebase tables ./data.db

# Run a read query; rows print as JSON objects
litebase query ./data.db "SELECT id, name FROM users ORDER BY id"

litebase --version

MCP サーバーが開くデータベースは、次の優先順位で決まります。mcp の後のパス引数、LITEBASE_DB 環境変数、現在のディレクトリにある ./litebase.db の順です。

終了コード：成功時は 0、クエリまたはデータベース自体でエラーが発生した場合は 1（理由を示すメッセージが表示されます）、使用方法に誤りがある場合は 2 です。

MCP サーバー

1 つの実行ファイルで両方の使い方に対応しています。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/litebase mcp ./data.db

MCP クライアントの設定：

{
  "mcpServers": {
    "litebase": {
      "command": "npx",
      "args": ["-y", "@reneturcios/litebase", "mcp", "./data.db"]
    }
  }
}

データベースは最初のツール呼び出し時に遅延して開かれるため、サーバーを起動しただけではファイルは作成されません。

ツール

ツール	入力	説明
read_query	query（文字列、必須）	1 つの SELECT（または WITH ... SELECT）文を実行し、列名とオブジェクト形式の行を返します。
write_query	query（文字列、必須）	1 つの INSERT、UPDATE、または DELETE 文を実行し、影響を受けた行数と最後に挿入された行の rowid を報告します。
create_table	query（文字列、必須）	1 つの CREATE TABLE 文を実行します。
list_tables	—	データベースのユーザーテーブルを一覧表示します（SQLite の内部テーブル sqlite_% は表示されません）。
describe_table	table_name（文字列、必須）	テーブルの列と、宣言された型、NULL 許容性、デフォルト値、主キーのフラグを返します。
append_insight	insight（文字列、必須）	インメモリの知見メモにメモを追加し、これまでのメモ全体を返します。

文のガード

各ツールは、その用途に合った種類の文のみを一度に 1 つ受け付けます。

• read_query は、SELECT または WITH で始まらない文を拒否します。
• write_query は、INSERT、UPDATE、DELETE 以外の文（SELECT、CREATE、DROP など）を拒否します。
• create_table は、CREATE TABLE 以外の文を拒否します。
• ; の後に紛れ込ませた 2 つ目の文は、実行前に拒否されます。
• describe_table が受け付けるのは、英字、数字、アンダースコアで構成された単純なテーブル名のみです。名前は PRAGMA に渡されるため、パラメーター化ではなく検証されます。

ガードによる拒否や SQL エラーは、問題を示すメッセージとともにツールエラーとして返されます。拒否された呼び出しでは何も実行されません。

知見メモ

append_insight はサーバーインスタンス上に番号付きのメモを保持します。呼び出すたびに知見が 1 件追加され、メモ全体が返されるため、エージェントは分析セッション中に知見を蓄積し、まとめて読み返すことができます。メモはメモリ内にのみ保存され、データベースファイルには書き込まれず、サーバーの再起動後も保持されません。

開発

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

テストはインメモリデータベースと一時ファイルのデータベースを使って実行され、ネットワークアクセスは不要です。

ライセンス

MIT — 詳細は LICENSE を参照してください。