io.github.CloudCorpRecords/litebase

litebase

litebase gives you a SQLite database you can drive from a terminal or hand to an agent as an MCP server. It covers the everyday loop of working with a small database: create tables, put rows in, change them, read them back, check what a table looks like, and keep a running memo of what you learned from the data along the way.

There is nothing to provision and no native addon to compile: the storage engine is the SQLite library built into Node itself (node:sqlite), so a "database" is just a file path — or :memory: when you want a throwaway one.

Install

npx @reneturcios/litebase tables ./data.db

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/litebase

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

Node version requirement

litebase's engine is Node's built-in node:sqlite module, which only exists in Node 22.5 and newer. The package's engines field says >=20 because that is the fleet standard, but that is an honest gap: on Node 20 the CLI and server start, and then fail the moment a database is opened, with an error that names the Node >= 22.5 requirement. Use Node 22.5+ (Node 24 recommended) to actually read or write data.

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

Which database the MCP server opens is resolved in this order: the path argument after mcp, then the LITEBASE_DB environment variable, then ./litebase.db in the current directory.

Exit codes: 0 on success, 1 when a query or the database itself errors (the message says why), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

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

MCP client configuration:

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

The database is opened lazily on the first tool call, so starting the server never creates a file by itself.

Tools

Statement guards

Each tool only accepts the kind of statement it is for, and only one statement at a time:

• read_query rejects anything that does not start with SELECT or WITH.
• write_query rejects SELECT, CREATE, DROP, and everything else that is not INSERT, UPDATE, or DELETE.
• create_table rejects anything that is not CREATE TABLE.
• A second statement smuggled in after a ; is rejected before anything executes.
• describe_table only accepts a plain table name (letters, digits, underscores) — the name goes into a PRAGMA, so it is validated rather than parameterised.

Guard rejections and SQL errors come back as tool errors with a message naming the problem; nothing is executed on a rejected call.

Insights memo

append_insight keeps a numbered memo on the server instance: every call appends one insight and returns the whole memo, so an agent can build up findings during an analysis session and read them back as a single text. The memo lives in memory only — it is not written to the database file and does not survive a server restart.

Development

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

Tests run against in-memory and temporary-file databases; no network access is needed.

License

MIT — see LICENSE.