shop-db MCP Server

A read-only Model Context Protocol server that gives AI agents analytical access to an e-commerce SQLite database (customers, orders, order_items, products) — without any ability to modify data.

Built for Node.js v24.19+, running TypeScript source files directly (no build step) using native node:sqlite and node:test.

Setup

npm install

The repository already includes a populated ./shop.db at the project root — no seeding step is needed. Nothing in npm start or npm test writes to it: the server opens it read-only, and the test suite builds its own throwaway databases under tests/ from tests/fixtures/seed.sql.

Run the server

npm start

The server communicates over stdio (StdioServerTransport) — it's meant to be launched by an MCP client (Claude Code, Claude Desktop, etc.), not run interactively.

Tests

npm test

Runs node --test against tests/, covering SQL validation edge cases (mutation keywords, comment-evasion, multi-statement injection, CTEs, EXPLAIN) and the three MCP tools end-to-end against isolated test databases built from tests/fixtures/seed.sql. The committed ./shop.db is never read or written by the test suite.

Configuring the database path

By default the server reads ./shop.db (relative to the working directory it's launched from). Override with the DB_PATH environment variable:

DB_PATH=/absolute/path/to/shop.db npm start

Tools

• list_tables — lists the 4 tables with a short description of each.

• describe_table — column definitions, types, primary keys, and up to 3 sample rows, for one table (tableName) or all tables (omit it).

• read_query — executes a read-only SELECT/WITH/EXPLAIN/PRAGMA query (query, required) and returns up to limit rows (optional, default 100, max 1000). Any mutation attempt (INSERT, UPDATE, DELETE, DROP, ...) is rejected with a clear error, even if disguised with SQL comments or wrapped in a CTE.

AI agent config

{
  "mcpServers": {
    "shop-db": {
      "command": "node",
      "args": ["/absolute/path/to/src/index.ts"],
      "env": {
        "DB_PATH": "/absolute/path/to/shop.db"
      }
    }
  }
}

Project docs

• AGENTS.md — instructions for AI coding agents working on this repo (also loaded as CLAUDE.md via symlink).

• CONTEXT.md — domain model and safety architecture.