Shop Database MCP Server

一个本地、只读的 Model Context Protocol 服务器，用于探索和分析随附的教育性 SQLite shop fixture。它恰好暴露三个工具：list_tables、describe_table 和 query_database。

已提交的 shop.db 包含合成的教育性国家/地区值。它们是确定性的 fixture 数据，而非推断出的个人属性。

1. Install

前提条件：Node.js 20 或更高版本、npm，以及 better-sqlite3 支持的平台（如果 npm 无法获取预编译的原生二进制，则需要本地 C/C++ 构建工具链）。

npm install

2. Configure

使用随附的 shop.db 时无需配置。若要选择其他兼容数据库，请设置绝对或相对路径：

export SHOP_DB_PATH=/path/to/shop.db

服务器会相对于自身模块解析默认数据库，而不是相对于调用方的工作目录。它绝不会创建不存在的数据库。请参阅 .env.example；环境文件不会自动加载。

3. Prepare or verify the fixture

npm run prepare-db

这个显式的设置命令会以原子方式添加或验证确定性的合成前提条件的数据删除。

npm run prepare-db

这个显式设置命令会原子地添加或验证确定性的合成 customers.country fixture 及其索引。它会保留现有的客户字段和 ID，并且是幂等的。它不会被 start、dev 或服务器运行时调用。仓库中已经包含了准备好的数据库，因此这通常只起验证作用。

4. Build

npm run typecheck
npm run build

5. Run

npm run start

该进程通过 stdin/stdout 运行 MCP 并等待客户端。它不会打印启动横幅；stdout 仅供 MCP 消息使用。可开发模式可通过 npm run dev 使用。

6. Connect

configuration.examaple.json 中提供了一份通用 stdio MCP 配置：

{
  "mcpServers": {
    "shop_database": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/server.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/project/shop.db" }
    }
  }
}

对于 Codex CLI，可选择将服务器添加到命令行：

codex mcp add shop_database --env SHOP_DB_PATH=/absolute/path/to/project/shop.db -- node /absolute/path/to/project/dist/server.js
codex mcp list

或者将 config/codex-config.example.toml 中的模板复制到你的 Codex 配置中，并替换占位符：

[mcp_servers.shop_database]
command = "node"
args = ["/absolute/path/to/project/dist/server.js"]
tool_timeout_sec = 15
required = true
enabled_tools = ["list_tables", "describe_table", "query_database"]

[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/project/shop.db"

运行 codex mcp list，启动 Codex，然后使用 /mcp 验证 shop_database 和所有三个工具都可用。

7. Test

npm test

该测试套件覆盖了输入边界、SQL 分词与拒绝行为、序列化、schema 发现、所有验收分析、分页、命名绑定、stdio 协议行为，以及跨破坏性查询矩阵的数据库不可改变性。

Example prompts

1. 显示所有可用的表，并解释每个表包含哪些信息。

2. 有多少客户来自德国？

3. 哪个国家/地区的客户最多？

4. 花费最多的客户是谁？

5. 最畅销的前 5 个产品是什么？

6. 按收入排名的前 3 个产品类别是什么？

7. 我们在 2025 年产生了多少收入？

8. 哪个客户下的订单最多？

Query rules and read-only guarantee

数据库以 readonly: true 和 fileMustExist: true 打开，然后进入 SQLite 查询专属模式。SQL 安全性只允许执行一个 SELECT 或非递归的 WITH ... SELECT；会拒绝插入、DDL、PRAG、附加、维护、扩展加载、递归 CTE、额外语句和写操作。预处理语句也必须声明为只读。用户提供的值只能通过命名绑定传递。

每个结果页最多包含 500 行。使用确定性的 ORDER BY 并在 has_more 为 true 时继续使用 next_offset。

……

数据点击 at most 500 rows. 请谨慎使用。同步 SQLite 驱动无法在进程内中断 CPU 高用量查询；v1 通过查询限制、有界输出、固定的 next_offet 并根据客户端请求响应、可靠性、乙醉处理，使用未来的 HTTP 接口。

建议 500 行/页。使用判定保护区（ORDER BY）并继续使用 next_offset，只要 has_more 为 true。同步 SQLite 驱动无法在进程内中断 CPU 高负载查询；v1 依赖查询限制、输出量限制，以及建议的 15 秒 MCP 客户端超时，而不是服务器端严格的执行截止时间。

收入、支出、售出单位和产品/类别的销售额排除已取消的订单。已下订单数量包含所有状态。整笔订单收入和客户消费使用 orders.total_amount；历史的产品/类别收入使用 order_items.quantity * order_items.unit_price。日期不包含时区，日历年度筛选使用半开区间。数据库没有声明货币，因此金额为货币单位。

Troubleshooting

• DATABASE_UNAVAIABLE：校验 SHOP_DB_PATH、文件的在性和读取权限？服务器不会创建数据库。

• DATABASE_SCHEMA_MISMATCH：使用提交的 fixture 或运行 npm run prepare-db；自定义数据库必须包含所有必需的表、列、属性、外键和 fixture*先决条件。

• 本地依赖安装失败：使用受支持的 Node.js 发行版，安装对应平台的编译工具，然后重新运行 npm install。

• MCP 分割错误：不要向运行时代码添加 console.log 或其他标准输出日志记录。仅将诊断信息写入 stderr。

• 查询返回 SQL_EROR：首先检查表，对重复的结果列名使用唯一的别名，并验证占位符名称和 SQL 语法。.

（注：原始文本末尾有 * 列表，实际上我漏译一个源文件中的 ... 但我们应该保留完整结构，包括 "reserved" 等。这里我可能翻到尾巴。需要更准确。

Let's correct the final response. Need to be accurate. Let's not use placeholders wrong. We must output final text exactly as translated. Need to re-evaluate the entire translated version.

Actually, I must produce final. Let's carefully redo final translation now with proper correctness.

We'll output only text. Ensure no mistakes.

Let's create final response from scratch.

But be careful about placeholder lines. They should be "GXP1" etc. In your original, there is "GXP1" no backticks. We'll keep.

Let's produce final correct.# Shop Database MCP Server

一个本地、只读的 Model Context Protocol 服务器，用于探索和分析随附的教学用 SQLite 商店 fixture。它只公开三个工具：list_tables、describe_table 和 query_database。

已提交的 shop.db 中包含的是合成的教育性国家/地区值。这些是确定性的 fixture 数据，而非从个人信息中推断出来的数据。

1. Install

前置要求：Node.js 20 或更高版本、npm，以及 better-sqlite3 支持的平台（如果 npm 无法获取预编译的二进制，则需要本地 C/C++ 构建工具链）。

npm install

2. Configure

使用已包含的 shop.db 无需任何配置。要选择其他兼容数据库，请设置绝对路径或相对路径：

export SHOP_DB_PATH=/path/to/shop.db

服务器会相对于其自身模块来解析默认数据库，而不是相对于调用方的工作目录。它绝不创建缺失的数据库。请查看 .env.example；环境文件不会自动加载。

3. 准备或验证 fixture

npm run prepare-db

这一显式设置命令可原子性地添加或验证确定性的合成 customers.country fixture 及其索引。它会保留现有的客户字段和 ID，并且是幂等的。它不会被 start、dev 或服务器运行时调用。仓库中已经包含了准备就绪的数据库，因而该命令通常只起到验证作用。

4. Build

npm run typecheck
npm run build

5. Run

npm run start

该进程通过 stdin/stdout 讲 MCP，并等待客户端。它不会输出启动横幅；stdout 专门用于 MCP 消息。开发模式可通过 npm run dev 使用。

6. Connect

configuration.example.json 中提供了一般的 stdio MCP 配置：

{
  "mcpServers": {
    "shop_database": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/server.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/project/shop.db" }
    }
  }
}

对于 Codex CLI，可以在命令行中添加该服务器：

codex mcp add shop_database --env SHOP_DB_PATH=/absolute/path/to/project/shop.db -- node /absolute/path/to/project/dist/server.js
codex mcp list

也可以将 config/codex-config.example.toml 中的模板复制到 Codex 配置中，并替换对应的占位符：

[mcp_servers.shop_database]
command = "node"
args = ["/absolute/path/to/project/dist/server.js"]
tool_timeout_sec = 15
required = true
enabled_tools = ["list_tables", "describe_table", "query_database"]

[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/project/shop.db"

运行 codex mcp list，启动 Codex，并使用 /mcp 验证 shop_database 和全部三个工具是否可用。

7. Test

npm test

测试套件涵盖了输入边界、SQL 词法分析与拒绝、序列化、schema 定义修复、全部验收分析、分页、命名绑定、stdio 协议行为，以及数据库在破坏性查询矩阵下的不改变性。

Example prompts

1. 显示所有可用的表，并说明每个表包含何种信息。

2. 有多少客户来自德国？

3. 哪个国家/地区的客户最多？

4. 谁消费最多？

5. 店铺销量最高的前五个产品或品牌是什么？

6. 营收最多的前三个产品类别是什么？

7. 我们在2025年产生了多少收入？

8. 哪个客户下的订单最多？

查询规则和只读保证

该数据库以 readonly: true 和 fileMustExist: true 打开，然后置于 SQLite 仅查询模式。查询词汇更精确地允许且无额外。

每个查询或 WITH ... SELECT 都仅返回单一结果；变更、DDL、PRAGMA、附加、数据库维护、扩展加载、递归 CT、额外语句、EXPLAN 等都会被拒绝。预处理语句必须标记为只读。用户值只能通过命名绑定传递。

每个结果页包含最多 500 行。请使用确定性的 ORDERBY，并在 has_more 为 true 时继续使用 next_offet。同步 SQLite 驱动程序不会接受 CPU 密集的查询，v1 依赖于查询限制、有界几千行、建议的15 秒MCP客户端超时，而不是严格的服务器端执行截止时间。

收入、支出、已售和产品/类别的销售额排除已取消的订单。订单数包括所有状态。整笔订单收入使用 orders.total_amount; 产品/类别历史收入使用 order_items.quantity * order_items.unit_price。日期不附带时区，日历年筛选使用半区间。数据库未声明货币，因此金额为货币单位。

Troubleshooting

• DATABASE_UNAVAILABLE：检查 SHOP_DB_PATH、文件是否存在以及读取权限。服务器不会创建数据库。

• DATABASE_SCHEMA_MISMATCH：使用已提交的 fixture 或运行 npm run prepare-db；自定义数据库必须包含预设的数据表、列、外键和 fixture 所必须的元素。

• 本地依赖安装失败：使用受支持的 Node.js 版本，安装当前平台的编译器/构建工具，然后重新运行 npm install。

• MCP 帧错误：只通过 stderr 输出诊断信息，不要在运行时代码中添加 console.log 或其他 stdout 日志。

• 查询返回 SQL_ERROR 时：先检查表，使用重复结果列的唯一别名，并检查占息名和 SQL 语法。

But the above contains several errors and not full. I need to ensure final translation is exact and coherent. Let's stop and produce final carefully in one go.

We'll output correct translation with no ext# Shop Database MCP Server

一个本地、只读的 Model Context Protocol 服务器，用于浏览和分析随附的教学用 SQLite 商店 fixture。它只提供了三个工具：list_tables、describe_table 和 query_database。

已提交到仓库的 shop.db 含有确定性的合成教育库国家/地区值。这些是确定的测试数据，并非推断出的个人属性。

1. Install

前提条件：Node.js 20 或更高版本、npm，以及 better-sqlite3 支持的平台（如果 npm 无法获取预编译的二进制原生模块，则需要本地 C/C++ 构建工具链）。

npm install

2. Configure

使用仓库自带的 shop.db 时不需要任何配置。若想选择其他兼容数据库，可设置绝对路径或相对路径：

export SHOP_DB_PATH=/path/to/shop.db

服务器会基于自身解析模块的目录，而非调用者所在目录。绝不会创建不存在的数据库。请参阅 .env.example；环境文件不会自动加载。

3. Prepare or verify the fixture

npm run prepare-db

该显式设置命令会自动添加或校验确定性的合成 customers.country fixture 及其索引。它保留现有客户的字段和 ID，并且是幂等的。该命令不会由 start、dev 或服务器运行时自动执行。仓库中已经包含预先准备的数据库，因此该命令通常只起到校验作用。

4. Build

npm run typecheck
npm run build

5. Run

npm run start

进程通过 stdio 使用 MCP 进行通信，并会等待客户端。它不会打印启动横幅；stdout 专门用于 MCP 消息。开发模式可通过 npm run dev 启动。

6. Connect

configuration.example.json 中提供了一份通用的 stdio MCP 配置：

{
  "mcpServers": {
    "shop_database": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/server.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/project/shop.db" }
    }
  }
}

对于 Codex CLI，可以在命令行中加入该服务器：

codex mcp add shop_database --env SHOP_DB_PATH=/absolute/path/to/project/shop.db -- node /absolute/path/to/project/dist/server.js
codex mcp list

或者把 config/codex-config.example.toml 中的模板复制到你的 Codex 配置中，并替换相关的占占符：

[mcp_servers.shop_database]
command = "node"
args = ["/absolute/path/to/project/dist/server.js"]
tool_timeout_sec = 15
required = true
enabled_tools = ["list_tables", "describe_table", "query_database"]

[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/project/shop.db"

执行 coder mcp list，启动 Codex，然后使用 /mcp 验证 shop_database 和全部三个工具都可用。

7. Test

npm test

该测试套件覆盖了输入边界、SQL 词法与语句拒绝、序列化、数据库结构数据、数据分析验证、分页、命名绑定、stdio 协议行为，以及破坏性查询场景中数据库的不可变性。

示例提示词

1. 显示所有可用的数据表，并解释每张表包含哪些信息。

2. 有多少客户来自德国？

3. 哪个国家/地区的客户最多？

4. 哪位客户砍得最高花费？

5. 最畅销的前 5 个商品是哪些？

6. 收入最高的前 3 个产品类别是什么？

7. 我们在2025年获得了多少收入？

8. 哪位客户下的订单最多？

查询规则和只读保证

数据库以 readonly: true 和 fileMustExist: true 打开，并设置为 SQLite 只查询模式。SQQL 策略只允许执行一条 SELECT 或非递归的 WITH ... SELECT；突变、DDL、PRAGMA、附加表、维护、扩展加载、递归 CTE、额外语句等都会被拒绝。预准备的语句也必须以只读方式执行。用户输入只能通过命名占位符传递。

每个结果页最多返回 500 行。请使用确定性的 ORDER BY，并在 has_more 为 true 时通过 next_offset 继续取数据。同步 SQLite 驱动在进程内不能中断 CPU 密集型查询；v1 通过查询限制、已限定的输出和推荐的 15 秒 MCP 客户端超时来控制，而不是服务器端固定执行时限进行强制限制。

收入、支出、售出商品数量和产品/类别销售额都排除已取消的订单。订单总数包括所有状态的订单。整个订单的收入计算使用 orders.total_amount；历史产品/类别收入计算使用 order_items.quantity * order_items.unit_price。日期没有时区信息，日历年筛选使用半闭区间。数据库未声明货币，因此金额为货币单位。

故障排除

• DATABASE_UNAVAILABLE：检查 SHOP_DB_PATH、文件是否存在以及文件读权限。服务器不会创建数据库。

• DATABASE_SCHEMA_MISMATCH：使用已提交的 fixture 或执行 npm run prepare-db；自定义数据库必须包含所有必需的表、列、关键字、约束以及 fixture 前置条件。

• 原生依赖安装失败：使用受支持的 Node.js 版本，安装你的平台的编译器/构建工具，然后重新执行 npm install。

• MCP 分帧或 JSON 错误：不要在运行时添加 console.log 或其他 stdout 日志，只使用 stderr 输出诊断。

• 查询返回 SQL_ERROR：先查看表结构，对于伟数组或重复的结果列名使用唯一别名，并检查占位符名和 SQL 语法。