litebase

litebase

litebase 为你提供一个 SQLite 数据库，你可以通过终端操作它，也可以将其作为 MCP 服务交给 Agent 使用。它涵盖了处理小型数据库的日常流程：创建表、插入行、修改行、读取数据、查看表的结构，以及随时记录你从数据中获得的发现。

无需预配任何资源，也无需编译原生插件：存储引擎是 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 服务

同一个可执行文件支持两种用法。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（字符串，必填）	运行一条 SELECT（或 WITH ... SELECT）语句，并以对象形式返回列名和行数据。
write_query	query（字符串，必填）	运行一条 INSERT、UPDATE 或 DELETE 语句，并报告受影响的行数和最后插入行的 rowid。
create_table	query（字符串，必填）	运行一条 CREATE TABLE 语句。
list_tables	—	列出数据库中的用户表（隐藏 SQLite 内部的 sqlite_% 表）。
describe_table	table_name（字符串，必填）	返回表的列及其声明类型、是否可为空、默认值和主键标记。
append_insight	insight（字符串，必填）	向内存中的发现备忘录添加一条记录，并返回截至目前的完整备忘录文本。

语句限制

每个工具只接受其对应类型的语句，并且一次只能接受一条语句：

• read_query 会拒绝任何不以 SELECT 或 WITH 开头的内容。
• write_query 会拒绝 SELECT、CREATE、DROP，以及任何非 INSERT、UPDATE 或 DELETE 的内容。
• create_table 会拒绝任何非 CREATE TABLE 的内容。
• 如果在 ; 后偷偷附加第二条语句，该语句会在执行前被拒绝。
• describe_table 只接受普通表名（字母、数字、下划线）——名称会用于 PRAGMA，因此会先进行校验，而非参数化处理。

限制校验拒绝和 SQL 错误会以工具错误的形式返回，并说明问题所在；被拒绝的调用不会执行任何内容。

发现备忘录

append_insight 会在服务实例中维护一份带编号的备忘录：每次调用都会追加一条发现并返回完整备忘录，因此 Agent 可以在分析过程中逐步积累发现，并将它们作为一段完整文本读回。备忘录只保存在内存中——不会写入数据库文件，也不会在服务重启后保留。

开发

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。