mcp-server-dmdb

达梦 DM8 的 MCP server，基于官方 dmdb Node.js 驱动，用 TypeScript 实现。默认纯只读，写操作与改表结构分别由环境变量开关控制，未开启时对应工具根本不会注册。

快速开始

npm install
npm run build      # tsc -> dist/
npm test           # 构建 + node --test 跑门禁用例（43 条）
node scripts/probe-connect.mjs   # 验证数据库连通性
node scripts/e2e-mcp.mjs         # 端到端 JSON-RPC 验证（43 项检查）

要求 Node >= 20（ESM only）。

Related MCP server: mcp-dm8-server

接入 MCP 客户端

在客户端的 MCP 配置里加一条：

{
  "mcpServers": {
    "dmdb-local": {
      "command": "C:/Users/MI-Damon/.workbuddy/binaries/node/versions/22.22.2/node.exe",
      "args": ["D:/DevContainer/gitHubRepo/mcp-server-dmdb/dist/index.js"],
      "env": {
        "DM_HOST": "192.168.62.44",
        "DM_PORT": "5236",
        "DM_USER": "TRADE_MARKET",
        "DM_PASSWORD": "kdgc@2025",
        "DM_SCHEMA": "TRADE_MARKET",
        "DM_ALLOW_WRITE": "false",
        "DM_ALLOW_DDL": "false"
      }
    }
  }
}

Windows 上 command 必须写 node.exe 的完整路径。MCP 客户端用 Win32 spawn 启动进程，不带扩展名的 node 解析不到。

使用

典型使用流程：

1. 安装并构建：npm install && npm run build（生成 dist/index.js）。

2. 在 MCP 客户端的配置里加一条 mcpServers.dmdb（见上），填好 DM_* 连接信息。

3. 客户端启动本进程（stdio 传输），自动完成 initialize 握手并拉取 tools/list。

4. 调用工具：默认 9 个只读工具；设 DM_ALLOW_WRITE=true 出现 dm_execute_dml，再设 DM_ALLOW_DDL=true 出现 dm_execute_ddl，共 11 个。

5. 调试：先 node scripts/probe-connect.mjs 验证连通性，再用 dm_ping 确认两个写开关的运行时状态。

进程以本地子进程方式运行，凭据通过环境变量注入，不监听任何网络端口，无外部鉴权面。

支持的 MCP 协议

本 server 兼容 MCP（Model Context Protocol）2025-era 规范，基于官方 TypeScript SDK v2 实现。

兼容性边界

• 支持：stdio 传输、2025-06-18 握手、工具发现与调用、结构化输出（outputSchema / structuredContent）。

• 不支持：

  • SSE / Streamable HTTP 传输（仅 stdio）；

  • OAuth 等网络鉴权（凭据由环境变量注入，进程本地运行，不暴露端口）；

  • 资源（resources）订阅、提示模板（prompts）、服务端主动日志推送（logging 通知）。

环境变量

工具清单

默认注册 9 个；DM_ALLOW_WRITE=true 加第 10 个；再开 DM_ALLOW_DDL=true 共 11 个。

安全边界

SQL 语句必须连续通过五层检查才会执行，任一层失败即拒绝：

1. 归一化 —— 词法扫描剥离注释（不误伤字符串字面量内的 -- 和 /* */）

2. 顶层切分 —— 分号必须位于末尾，否则拒绝。服务端本身不拦多语句：SELECT 1; SELECT 2 会被归类为 PL/SQL 块，只能靠这一层

3. 关键字黑名单 —— 在已抹平字符串字面量的文本上按词边界匹配

4. 服务端判定 —— getStatementInfo() 返回的语句类型；异常或缺失一律 fail-closed

5. 交叉裁决 —— 第 3 层与第 4 层结论必须一致

永久禁止（任何开关状态下都不放行）： TRUNCATE、DROP DATABASE/USER/SCHEMA/TABLESPACE/ROLE、ALTER DATABASE/SYSTEM/SESSION、SHUTDOWN、GRANT、REVOKE、SP_*、SF_*、DBMS_*、EXECUTE IMMEDIATE。

DDL 额外三道锁：

• 上面的永久黑名单

• DROP TABLE/VIEW/INDEX/SEQUENCE 与 ALTER TABLE ... DROP COLUMN 必须传 confirm，值严格等于 DROP <对象名>

• 每条 DDL 写审计日志（stderr，不受 DM_LOG_LEVEL 影响）

DML 保护：update/delete 强制要求 where；autoCommit=false 执行 → 超 max_rows_affected 即回滚，否则提交；建议先用 dry_run=true 统计命中行数。

达梦的 DDL 隐式提交，包不进事务，无法回滚。

已知行为与坑

连接加密默认关闭

dmdb 的 loginEncrypt 默认为 true，但其加密套件在 Node 17+ 的 OpenSSL 3 下会被拒绝：

errCode 6071 消息加密失败
error:0308010C:digital envelope routines::unsupported

所以默认改为 false（想强制加密可显式设 DM_LOGIN_ENCRYPT=true）。本驱动只暴露 true/false，不能指定套件。

BIGINT 精度

DM8 的 BIGINT 主键普遍超过 2^53，驱动的默认 number 转换会静默抹平末三位：

真实值 1989221485636136962  ->  到达 JS 时变成 1989221485636137000

fetchAsString: [dmdb.NUMBER] 修不了——DM8 里 BIGINT 与 NUMBER 是不同类型。本实现在检测到不安全整数后，只把出问题的那几列用字符串重读一次，因此正常数值列仍是数字，而 ID 保持完整精度。

分页

DM8 原生支持 LIMIT ? OFFSET ? 且可绑定参数（官方实测执行计划优于 ROWNUM/TOP）。dm_query 要求分页写在 SQL 里、值放 params，服务端不做子查询包装——包装会包不住 WITH CTE。

执行计划要用 EXPLAIN FOR

裸 EXPLAIN <sql> 不返回结果集，只回 rowsAffected。必须用 EXPLAIN FOR <sql>。也因此 EXPLAIN 不接受绑定参数，dm_explain 会把 params 安全地内联为字面量。

行数统计

ALL_TABLES.NUM_ROWS 来自统计信息，本库多数表未收集，值为 NULL。不要拿 dm_list_tables 里的 NUM_ROWS 当真实行数，用 dm_table_count。

语句类型码

getStatementInfo() 返回的是达梦内部码，与 dmdb 自带 .d.ts 声明的 STMT_TYPE_*（声称 SELECT=1）完全不同。实测值：

SELECT ... FOR UPDATE 与普通 SELECT 同为 160，所以 FOR UPDATE 只能靠关键字拦截。

标识符大小写

本实例（192.168.62.44）标识符大小写不敏感，data_after_sale 与 DATA_AFTER_SALE 都能命中。但这取决于服务端 CASE_SENSITIVE 参数，不是 DM8 的保证，所以字典查询一律用 UPPER(...) = UPPER(?) 比较。

依赖

运行时只有 3 个，刻意保持最小：

开发依赖：typescript@^5.9.3（不用 7.x——那是 Go 重写的 tsgo）、@types/node@^22.19.1。

不引入 ORM：达梦没有 Prisma/Drizzle/Knex/MikroORM 方言，社区 fork（typeorm-dm、sequelize-dm8 等）周下载量仅个位数到两位数且基座老旧。更重要的是场景错配——ORM 的价值是实体映射，而 MCP 是运行时动态发现 schema，Entity 模型完全用不上。

测试用 Node 22 内置 node --test，不引 jest/vitest。

附录：字典视图真实列名

以下在 192.168.62.44:5236 实测所得，与 Oracle 文档有出入，勿照搬 Oracle 经验：

注意不对称：索引位置列叫 COLUMN_POSITION，约束位置列叫 POSITION。

SP_TABLEDEF(schema, table) 可用，返回 COLUMN_VALUE 列拼成的 DDL 文本。

目录结构

src/
├─ index.ts            stdout 保护 + serveStdio + 退出清理
├─ server.ts           createServer()：建 McpServer 并按需注册工具
├─ config.ts           环境变量解析
├─ log.ts              stderr-only 日志 + DDL/DML 审计
├─ db/
│  ├─ driver.ts        【唯一 import dmdb 的地方】CJS/ESM 互操作 + 真实语句类型码
│  ├─ connection.ts    懒加载/ping探活/毒化重连/mutex串行/大整数精确化重读
│  ├─ sql-guard.ts     五层门禁
│  ├─ identifiers.ts   标识符校验与引号
│  └─ types.ts
├─ tools/              register.ts（按开关注册）+ 每个工具一个文件
└─ format/             序列化 / 三层截断 / markdown 渲染
scripts/               probe-connect / verify-dict / e2e-mcp