Configuration

Requirements

• Node v24.14.1 (.nvmrc)
• pnpm@9.15.3 — pinned via packageManager; npm/yarn are not supported.

Environment variables

Loaded via envee -f .env -- in every dev and start script. Nothing is required — the defaults give you a working server.

Variable	Required	Default	Description
SQLITE_PATH		./data/music.db	Path to the SQLite database file. Parent directory is auto-created.
PORT		3000	Port the Hono server listens on.

If you want a .env anyway:

.env

PORT=3000
# SQLITE_PATH=./data/music.db   # optional override

Local database

mcp42 uses an embedded SQLite database via better-sqlite3 — no separate service to run. The file is created automatically on first connection at SQLITE_PATH (default ./data/music.db).

Apply the schema and, optionally, the curated knowledge graph:

pnpm db:migrate
pnpm db:seed   # optional — loads progressions, modes, voicings, cadences

The search-* and list-* tools return empty results until you’ve run db:seed.

Scripts

Command	What it does
pnpm dev	Hot-reload dev server via tsx watch.
pnpm start	One-shot run via tsx (no build).
pnpm build	Compiles the server with tsc and builds these docs.
pnpm start:prod	Runs the compiled output from dist/.
pnpm types	Type-check only.
pnpm lint	ESLint, type-aware.
pnpm test / pnpm test:watch	Vitest.
pnpm format / pnpm format:check	Prettier.
pnpm checks	format:check + lint + types + test (matches CI).
pnpm db:generate	drizzle-kit generate — emit SQL migrations from schema.
pnpm db:migrate	Apply pending migrations to the SQLite database.
pnpm db:seed	Load the curated music knowledge graph.
pnpm docs:gen	Regenerate the per-tool MDX reference from Zod schemas.
pnpm docs:dev	Run the Starlight dev server for these docs.
pnpm docs:build	Build the docs into public/docs/.

Docker

docker build -t mcp42 .
docker run --rm -p 3000:3000 mcp42

The multi-stage build on node:24.14.1-alpine produces a single image that serves the landing page at /, the docs at /docs/, the MCP transport at /mcp and a health probe at /health. Runs as non-root user nodejs.

The image runs pnpm db:migrate && pnpm db:seed at build time, so the SQLite DB is baked in at /app/data/music.db and the container is ready to serve as soon as it starts — no init step. Mount a volume at /app/data if you want writes to persist across container restarts.

Note

The docs you’re reading right now are built during pnpm build and shipped inside the same image, so a single deployment serves the API and the docs together.

How the docs reference stays in sync

Every page under Tools is generated from the same registerTool calls the running MCP server uses — see scripts/generate-tool-docs.ts. The generator:

1. Imports registerAllTools from src/mcp/tools/index.ts.
2. Passes a fake McpServer shim that captures each registration: name, title, description, inputSchema, outputSchema, annotations.
3. Converts each Zod schema to JSON Schema via zod-to-json-schema.
4. Emits one MDX file per tool into docs-src/src/content/docs/tools/.

The generator runs as part of pnpm build. The tool MDX files are gitignored so the source of truth is always the code.