Shop Analytics MCP Server

一个通过 stdio 运行的只读 MCP 服务器，让 AI 智能体能够回答关于在线商店 SQLite 数据库（customers、products、orders、order_items）的分析性问题——而它永远无法修改该数据库。

完整的设计依据（决策日志、schema、安全模型、测试策略）见 SPEC.md。

环境要求

• Node.js >= 24.10.0（node:sqlite 的 setAuthorizer 需要此版本，用于实现下文的只读保证）。运行 node --version 检查。

• 除 npm ci 安装的内容外，没有其他运行时依赖。

Related MCP server: db-mcp

安装 → 配置 → 运行 → 连接

npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start

• shop.db 已随仓库提供，开箱即用。如果需要从 schema 确定性重建它，请运行 npm run seed（见下文 数据库）。

• SHOP_DB_PATH 是可选的；默认值是当前工作目录下的 shop.db。源码中没有任何位置硬编码绝对路径。

• 服务器仅通过 stdio 执行 MCP 通信——没有 HTTP 服务器，也没有其他需要运行的东西。

连接 AI 智能体

两个客户端的配置示例见 config/：

• config/claude-code.mcp.json——将其复制到项目的 .mcp.json 中，或使用其中的 shop-analytics 条目运行 claude mcp add-json。请先为 args/env 填入绝对路径。

• config/codex.mcp.toml——将 [mcp_servers.shop-analytics] 表复制到 ~/.codex/config.toml（或项目级的 .codex/config.toml），或使用该文件头部注释里的 codex mcp add 命令。

如果不想特定依赖某个具体的智能体，而想手动试验这个服务器，可以使用不依赖特定工具的 MCP Inspector：

SHOP_DB_PATH=$(pwd)/shop.db npx @modelcontextprotocol/inspector node dist/src/index.js

工具

服务器恰好暴露 8 个专门的只读工具——没有任何工具接受或执行任意 SQL。每个成功响应都是 { "data": [...], "meta": {...} }；每个错误都是一个简单、安全、人类可读的消息（不含 SQL、文件路径或堆栈跟踪），并以 isError: true 标记。

from/to 采用 YYYY-MM-DD 格式，定义了一个半开 UTC 区间 [from, to)；from 必须严格早于 to。所有财务和计数指标都会排除状态为 cancelled 的订单。每个工具的完整契约（确切的响应结构、并列规则）见 SPEC.md §4。

安全

三层独立、纵深防御的机制保证数据库永远不会被修改，即使面对一个对抗性提示词，例如 “删除所有已取消的订单”：

1. SQLite 连接通过 readOnly: true 打开。

2. 打开后立即设置 PRAGMA query_only = ON。

3. 有一个 SQLite authorizer 明确拒绝对所有写/DDL 操作，例如（INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、ATTACH、DETACH、事务等，并有显式拒绝事务的机制）。

此外，没有任何工具接受原始 SQL、表名或列名，所有查询都是固定的预编译语句，所有输入都经过 zod 校验，并作为绑定参数传入，从不做字符串插值。

数据库

shop.db 由 database/schema.sql 通过一个确定性的 seed 脚本生成，每次重新运行都会产生逐字节一致的数据（固定 PRNG 种子，不依赖墙钟时间）：

npm run seed   # builds, then (re)writes ./shop.db from schema.sql + the seed script

seed 脚本还会在生成时断言数据集没有歧义的排行榜（例如唯一的最佳国家、唯一的最大消费者），并且 2025 年的营收不为零——见 SPEC.md §3。

开发

npm run build           # tsc + copy database/schema.sql into dist/
npm run test:unit        # business logic, in isolation, against fixture databases
npm run test:integration # spawns the built server over stdio via the MCP SDK client
npm test                 # both

本项目以 TDD 方式构建：对每个模块，先编写失败的测试，再是工具逐项实现。集成测试套件端到端覆盖了全部 8 个验收场景、SQL 注入形态的输入、无效参数组合，并断言每次运行后数据库文件的 SHA-256 哈希值不变。

项目结构

database/       schema.sql + the deterministic seed generator
src/
  db.ts          read-only SQLite connection (see Safety above)
  errors.ts      error taxonomy, safe error formatting
  validation.ts  zod schemas shared across tools (dates, limits, periods)
  period.ts      half-open period SQL clause builder
  tools/         one module per tool: pure query function + types
  server.ts      registers all 8 tools on the MCP server
  index.ts       stdio entrypoint
test/
  unit/          one file per module/tool, fixture-based
  integration/   spawns dist/src/index.js over stdio via the MCP SDK client
config/         example client configuration (Claude Code, Codex CLI)