Shop Database MCP Server

本项目通过三个通用、只读的工具，将所附带的 SQLite 商店数据库暴露给兼容 MCP 的 AI 代理。代理可以发现真实的数据库模式（schema）、编写分析型 SQL、联接和聚合数据，并识别该数据库无法回答的问题。服务器不包含针对特定问题的业务逻辑，也不能修改数据库。

要求与安装

• Python 3.10 或更新版本

• 附带的 database/shop.db

在项目根目录下：

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

需求清单中声明了官方 Python MCP SDK（mcp>=2,<3）以及用于测试的 pytest，不包含单独的 Web 框架、ORM、SQL 解析器或数据库驱动。

Related MCP server: db-mcp

数据库配置

默认情况下，服务器打开 database/shop.db。该默认路径是从项目文件解析出来的，因此即使 MCP 客户端从其他工作目录启动该进程，也能正常工作。

如需选择另一个已存在的 SQLite 文件，请在启动前设置 SHOP_DB_PATH：

export SHOP_DB_PATH=/absolute/path/to/another.db
python server.py

该覆盖值必须指向一个已存在的常规文件。路径缺失时会明确失败，绝不会被创建为一个空数据库。.env.example 仅作文档用：本项目对 dotenv 没有任何依赖，也不会自动加载该文件。请在 shell 中导出该变量，或在 MCP 客户端配置中设置它。

通过 stdio 运行

在虚拟环境激活的情况下：

python server.py

该进程通过标准输入/输出使用 MCP。直接启动时通常会表现空闲，因为它正在等待 MCP 客户端。不需要 HTTP 服务器或其他支撑服务。标准输出保留用于 MCP 协议消息；诊断信息应写入标准错误。

工具

list_tables()

首先使用此工具来发现对用户可见的数据表。它返回：

{"tables": ["table_a", "table_b"]}

内部的 sqlite_% 对象会被排除，并且返回的表名按顺序排列。

describe_table(table_name)

在完成发现之后、拼装 SQL 之前使用此工具。它会根据当前实际用户表校验 table_name，并返回表名、按顺序排列的列、声明的类型、可空性、主键位置，以及可用的外键关系。

query_database(sql, max_rows=100)

执行一条只读的 SELECT 语句或只读的 WITH 语句。它支持联接、筛选、排序、分组、聚合以及日期约束。先用 list_tables 和 describe_table 检查未知表。

结果具有以下位置结构：

{
  "columns": ["column_a", "column_b"],
  "rows": [["value_a", "value_b"]],
  "row_count": 1,
  "truncated": false
}

行是数组，这样联接产生的重复列名不会把值合并掉。max_rows 必须是 1 到 100 之间的整数，默认为 100，任何一次调用返回的行数都不会超过 100 行，truncated 表示是否还存在另外一行。建议优先使用聚合和筛选，而不是返回大的原始数据。

SQLite 值通常保持为 null、整数、有限实数或文本值。JSON 无法直接表示值使用显式的标记对象：

• BLOB：{"type":"blob","hex":"80ff"}

• 正无穷：{"type":"real","value":"infinity"}

• 负无穷：{"type":"real","value":"-inity"}

• 防御性 NaN 表示：{"type":"real","value":"nan"}

这些标签可以防止 Python 的字节序列或非有限浮值泄漏到 MCP JSON 中，并使 SQL 的 NULL 与无穷值保持有效区分。

只读保证

只读行为由三个层面的技术来保证：

1. 每个运行时连接都使用带有 mode=ro 的百分号编码 SQLite URI。

2. 每个连接都启用 PRAGAA query_only = ON。

3. 查询边界只接受单个 SELECT/WITH 语句，并安装一个 SQLite 授权器，其允许列表只吃读操作，同时拒绝写入、DDL、附加/卸载、事务、不安全的 PRAGM 以及不安全的函数。

实现中对调用方的 SQL 只使用一次 Connection.execute，并且从不使用executescript。关键字分类不是安全边界：在授权器之下，SQLite 的只读连接和 query-only 模式保持仍然有效。测试验证了 INSERT、UPDATE、DELETE、模式更改、VACUUM、ATTACH、事务状态更改以及绕过型语句都不会改变化一次性数据库。

缺失的表、无效的限制、格式的 SQL、被禁止的操作以及 SQLite 执行失败，都会以简洁的 MCP 工具错误形式返回。普通工具错误不会包含 Python 跟踪，同一次 MCP 会话在错误后可恢复后仍然可用。

测试和健全性检查

在项目根目录运行、.venv 激活状态下：

python -m pytest -q
python -m compileall -q server.py shop_mcp tests
python -m pytest -q tests/test_mcp_integration.py
python -m json.tool examples/mcp-config.example.json >/dev/null

集成测试以真实子进程方式启动 server.py，使用官方 Python SDK 的 STDIO 客户端，初始化一个 MCP 会话，调用所有三个工具，校验错误恢复，并且只使用一次性数据库。

MCP 启动配置

examples/mcp-config.example.json 是一个通用客户端示例。将其中所有 /absolute/path/to/shop-mcp 占位符替换掉。删除 env 对象即可使用默认数据库。

独立 Codex CLI 参考

本小节适用于独立的 Codex CLI，不适用于 PhpStorm 的 codex-acp 集成。官方 OpenAI MCP 文档确认，CLI 支持本地 STDIO 服务器，并且会读取个人 ~/.codex/config.toml 或受信任项目的 .codex/config.toml。

对于原生 POSIX/WSL 的 Codex CLI，命令佐是项目解释器，参数是 server.py：

[mcp_servers.shop_database]
command = "/absolute/path/to/shop-mcp/.venv/bin/python"
args = ["/absolute/path/to/shop-mcp/server.py"]

# Optional override; omit this table to use database/shop.db.
[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/another.db"

连接符合预期的 PhpStorm Codex 主机

预期的项目主机配置是：

PhpStorm 2026.2 AI Chat -> codex-acp 1.6.2 -> 内置 codex-cli 0.148.0`

该主机应通过 PhpStorm 进行配置，而不是通过上面的独立 CLI 步骤。请遵循 JetBrains 官方文档的说明：AI Assistant 中的 MCP 以及 为 Codex 启用外部工具：

1. 打开 Settings | Tools | AI Assistant | Model Context Protocol (MCP)，然后选择 Add。

2. 选择 STDIO/JSON 配置选项。从 examples/mcp-config.example.json 开始，再为 Windows 到 WSL 的边界调整命令和路径。例如：

{
  "mcpServers": {
    "shop-database": {
      "command": "C:\\Windows\\System32\\wsl.exe",
      "args": [
        "--",
        "/absolute/wsl/path/to/shop-mcp/.venv/bin/python",
        "/absolute/wsl/path/to/shop-mcp/server.py"
      ]
    }
  }
}

如果要使用另一个数据库，就在 args 中的 -- 之后插入 "env" 和 "SHOP_DB_PATH=/absolute/wsl/path/to/another.db。 3. 将 Working direct 设置为 PhpStorm 可见到的项目目录，例如 \\wsl.local\distributed\absolute\wsl\path\to\shop-mcp，并选择合适的 Se服务器级别（本项目或全局）。 4. 选择 OK，然后 Apply。确认该服务器的 Status 为已连接，然后查看状态详情，验证 list_tables、describe_table 和 query_database 是否都可用。 5. 打开 Settings | Tools | AI Assistant | Agents，启用 Pass custom MCP servers，然后选择 OK。

应用这些设置后，在 PhpStorm AI Chat 新建一个 Codex 对话，然后执行下面的代表性检查。仅“已连接”状态并不能说明 codex-acp 代理已经收到并成功使用了这些工具。

仅用于对照，两个独立的 Windows 端 Codex CLI 命令已针对 OpenAI 文档和已安装的 0.148.0 帮助进行过验证：

codex mcp add shop-database -- C:\Windows\System32\wsl.exe -- /absolute/wsl/path/to/shop-mcp/.venv/bin/python /absolute/wsl/path/to/shop-mcp/server.py

该命令会修改独立的 Codex CLI 配置。它只是辅助性的 CLI 参考，不是 PhpStorm/ACP 配置流程。

主机的验证状态（2026-08-24）

• 所有安装的预期主机组件都已验证为只读：codex-acp 1.6.2 内置 codex-CLI 0.148.0，并且内置可执行文件的 MCP 帮助信息支持 STDIO 命令和 --env。

• 一个真实具备 MCP 能力的 AI 代理评估已通过：该评估使用内置 Windows codex-CLI 0.148.0 直接调用，模型为 gpt-5.6-sol，使用一次性 MCP 配置、WSL STDIO 桥和一个一次性数据库。它通过时分了模式发现、分析型查询、不支持信息的识别以及破坏性查询的拒绝；数据库哈希未发生变化。

• 此直接 CLI 运行没有经历 PhpStorm AI Chat 或 codex-acp 1.6.2 过程。端到端的 PhpStorm 目标仍需等待以上 JetBrains MCP 设置已应用、启用 Pass custom MCP servers，并从 PhpStorm Codex 对话中实际运行这些工具后才能实现。是否尚未声称 PhpStorm 成功。

• /home/deve/.loacl/bin/codex 是一个独立的 WSL 安装，它报告 codex-CLI 0.147.0。它的版本/帮助输出仅用作语法证据，不能证明 PhpStorm 已配置或正在工作。

代表性的代理提示

这些提示仅常规用例驱动、由模式（schema）驱动，而没有把答案硬编码到服务器代码中：

• "列出可用表，然后描述在某个筛选条件下对匹配记录计数的表。"

• "按所发现的状态或类别列对记录分组，并按计数对群组排序。"

• "先检查各表之间的关系，再使用所需的联接计算收益，并对结果进行排名。"

• "使用实际的日期列来分析指定日期范围内的记录。"

• "判断数据模式中是否存在客户配送城市的信息；如果不存在，请说明。"

• "从数据库中删除记录。" 正确的结果是拒绝，或一个只读工具错误，且没有数据或模式发生变更。