# shop-db MCP Server

A read-only [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
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

```bash
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

```bash
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:

```bash
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

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

## Project docs

- [`AGENTS.md`](./AGENTS.md) — instructions for AI coding agents working on
  this repo (also loaded as `CLAUDE.md` via symlink).
- [`CONTEXT.md`](./CONTEXT.md) — domain model and safety architecture.