shop-db MCP 服务器

一个只读的 Model Context Protocol 服务器，为 AI 代理提供对电子商务 SQLite 数据库（customers、orders、order_items、products）的分析访问权限——而没有任何修改数据的能力。

为 Node.js v24.19+ 构建，直接运行 TypeScript 源文件（无需构建步骤），使用原生 node:sqlite 和 node:test。

设置

npm install

仓库已在项目根目录包含一个已填充的 ./shop.db — 无需种子步骤。npm start 或 npm test 中的任何内容都不会写入它：服务器以只读方式打开它，测试套件从 tests/fixtures/seed.sql 在 tests/ 下构建自己的临时数据库。

Related MCP server: shop-mcp

运行服务器

npm start

服务器通过 stdio（StdioServerTransport）进行通信——它旨在由 MCP 客户端（Claude Code、Claude Desktop 等）启动，而不是交互式运行。

测试

npm test

对 tests/ 运行 node --test，涵盖 SQL 验证边缘情况（突变关键字、注释规避、多语句注入、CTE、EXPLAIN）以及针对从 tests/fixtures/seed.sql 构建的隔离测试数据库对三个 MCP 工具进行端到端测试。提交的 ./shop.db 永远不会被测试套件读取或写入。

配置数据库路径

默认情况下，服务器读取 ./shop.db（相对于启动它的工作目录）。使用 DB_PATH 环境变量覆盖：

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

工具

• list_tables — 列出 4 个表，并附上每个表的简短描述。

• describe_table — 列定义、类型、主键以及最多 3 个示例行，针对一个表（tableName）或所有表（省略该参数）。

• read_query — 执行只读的 SELECT/WITH/EXPLAIN/PRAGMA 查询（query，必填），并返回最多 limit 行（可选，默认 100，最大 1000）。任何突变尝试（INSERT、UPDATE、DELETE、DROP 等）都会被拒绝并给出明确错误，即使使用 SQL 注释伪装或包裹在 CTE 中。

AI 代理配置

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

项目文档

• AGENTS.md — 为在此仓库上工作的 AI 编码代理提供的说明（也通过符号链接作为 CLAUDE.md 加载）。

• CONTEXT.md — 领域模型和安全架构。