agentdb mcp start crashes -32000 under npx: better-sqlite3 peerDependency not installed (static import on CLI boot path)

[ciprianmelian]

Summary

(agentdb@3.0.0-alpha.10 — filed here since npm view agentdb points bugs at this repo.)

Registering the agentdb MCP server the documented way — npx -y agentdb@3.0.0-alpha.10 mcp start in a Claude Code .mcp.json — crashes on a fresh npx cache, because better-sqlite3 is declared as a peerDependency and npx -y (and npm install -g) do not install peer deps. The stdio process exits before it can speak JSON-RPC, so the MCP client reports Failed to reconnect to agentdb: -32000.

Version

agentdb@3.0.0-alpha.10

Reproduction

# in an environment with no ancestor node_modules/better-sqlite3
npx -y agentdb@3.0.0-alpha.10 mcp start

→

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'better-sqlite3'
  imported from .../node_modules/agentdb/dist/src/cli/commands/migrate.js

Root cause

package.json declares better-sqlite3: ^11.8.1 (also sqlite3, @xenova/transformers) as peerDependencies, which npx -y / npm i -g do not install. The CLI entry dist/src/cli/agentdb-cli.js statically imports dist/src/cli/commands/migrate.js, whose top-level line is import Database from 'better-sqlite3'. So the CLI module graph fails to load before the mcp subcommand runs — even though the MCP server itself (dist/src/mcp/agentdb-mcp-server.js) uses the bundled sql.js (a regular dep) for its DB layer and never needs better-sqlite3. A static top-level import of an un-installed peer on the CLI boot path takes down every subcommand, including mcp start.

Suggested fixes (any one resolves it)

1. Lazy-load the migrate better-sqlite3 import — const Database = (await import('better-sqlite3')).default inside migrateCommand, so the CLI boots (and mcp start runs) without the peer. Matches how @xenova/transformers is already handled (lazy await import() in EmbeddingService).
2. Move better-sqlite3 to dependencies/optionalDependencies so npx/npm i provision it.
3. Document global-install launch for the MCP server (npm i -g agentdb@3.0.0-alpha.10 better-sqlite3@^11.8.1, then .mcp.json → command:"agentdb" not npx). That's the workaround we shipped, but a stdio MCP server that can't run under its own documented npx invocation is a footgun worth fixing in the package.

Workaround

npm i -g agentdb@3.0.0-alpha.10 better-sqlite3@^11.8.1

.mcp.json: "agentdb": { "command": "agentdb", "args": ["mcp","start"] }. Note better-sqlite3 is a NODE_MODULE_VERSION-pinned native addon → re-install after a Node major upgrade.