Skip to main content
Glama
mcp-server-dmdb

mcp-server-dmdb

by SpringDamon

mcp-server-dmdb

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

安装

npm install -g mcp-server-dmdb@latest     # 全局安装最新版
npx -y mcp-server-dmdb@latest             # 或按需临时拉取最新版,不落盘

@latest 始终拉取 npm 上最新的已发布版本(每次 npm publish 后自动生效),不锁具体版本号。

要求 Node >= 20(ESM only),无原生编译步骤。

Related MCP server: mcp-dm8-server

接入 MCP 客户端

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

{
  "mcpServers": {
    "dmdb-dev": {
      "command": "npx",
      "args": ["-y", "mcp-server-dmdb@latest"],
      "env": {
        "DM_HOST": "your-host",
        "DM_PORT": "5236",
        "DM_USER": "your-user",
        "DM_PASSWORD": "your-password",
        "DM_SCHEMA": "your-schema",
        "DM_ALLOW_WRITE": "false",
        "DM_ALLOW_DDL": "false"
      }
    }
  }
}

Windows 注意:MCP 客户端用 Win32 spawn 启动进程,npx 是 .cmd 包装脚本,常解析失败而表现为"客户端静默无响应"。建议改成直接指向 node.exe 和已安装包的绝对路径:

{
  "command": "C:/Program Files/nodejs/node.exe",
  "args": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/mcp-server-dmdb/dist/index.js"]
}

先 npm install -g mcp-server-dmdb@latest 装最新版,再用 npm root -g 确认上方路径。Linux / macOS 上 npx 写法没问题。

使用

  1. 按上文配好 DM_* 连接信息。

  2. 客户端以 stdio 方式启动本进程,自动完成 initialize 握手并拉取 tools/list。

  3. 调用工具:默认 9 个只读工具;设 DM_ALLOW_WRITE=true 出现 dm_execute_dml,再设 DM_ALLOW_DDL=true 出现 dm_execute_ddl,共 11 个。

  4. 排查连接:先用 dm_ping 确认连通性与两个写开关的运行时状态。

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

支持的 MCP 协议

本 server 兼容 MCP(Model Context Protocol)2025-era 规范,基于官方 TypeScript SDK v2 实现。

维度

说明

传输方式

stdio(标准输入/输出)。stdout 为 JSON-RPC 2.0 通道,所有日志走 stderr,避免污染协议流导致客户端静默卡死

SDK

@modelcontextprotocol/server v2(^2.0.0),ESM-only

协议版本

protocolVersion = 2025-06-18(legacy initialize 握手)。未启用 2026-07-28 的 opt-in 新协议,以保证与现有客户端(WorkBuddy / CodeBuddy / Claude Desktop 等)兼容

能力声明

仅 tools。未声明 resources / prompts / logging(日志直接写 stderr)

工具调用

JSON-RPC tools/call;每个工具带 title(人类可读标题)、inputSchema(zod v4 生成);部分带 outputSchema 并回传 structuredContent(结构化 JSON,便于客户端解析)

结果格式

以 content 数组(text)回传,并附带 structuredContent;超长单元格/总字符数按环境变量三层截断

连接模型

每次 stdio 连接对应一个独立 McpServer 实例(factory 模式);数据库连接懒加载,启动不触网,故 tools/list 即使库不可达也能立即返回

生命周期

捕获 SIGINT / SIGTERM,关闭连接池后退出;未捕获异常与 Promise 拒绝落 stderr,不致命

兼容性边界

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

  • 不支持:

    • SSE / Streamable HTTP 传输(仅 stdio);

    • OAuth 等网络鉴权(凭据由环境变量注入,进程本地运行,不暴露端口);

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

环境变量

变量

默认值

说明

DM_HOST

127.0.0.1

数据库地址

DM_PORT

5236

端口

DM_USER

必填

用户名

DM_PASSWORD

必填

密码

DM_SCHEMA

无

登录 schema

DM_ALLOW_WRITE

false

开启 dm_execute_dml

DM_ALLOW_DDL

false

开启 dm_execute_ddl

DM_MAX_ROWS

100

单次返回行数上限

DM_MAX_ROWS_HARD

1000

硬顶,DM_MAX_ROWS 不会超过它

DM_CELL_CHAR_LIMIT

200

单个单元格字符上限

DM_TOTAL_CHAR_LIMIT

24000

单次响应总字符上限

DM_CONNECT_TIMEOUT_MS

10000

连接超时

DM_SOCKET_TIMEOUT_MS

60000

网络超时(驱动原生)

DM_QUERY_TIMEOUT_MS

30000

JS 层兜底超时,触发即丢弃并重建连接

DM_PING_TIMEOUT_MS

3000

探活超时

DM_LOGIN_ENCRYPT

自动

见下文"连接加密"

DM_LOG_LEVEL

ERROR

OFF/ERROR/WARN/INFO/DEBUG

DM_DICT_SCOPE

all

all 用 ALL_* 视图;权限不足时改 user 用 USER_*

工具清单

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

工具

用途

开关

dm_ping

连接自检、服务端版本、实例信息、两个写开关的当前状态

—

dm_list_schemas

列出可访问的模式

—

dm_list_tables

按模式 + 表名关键字列模糊搜表,带行数与表注释

—

dm_describe_table

列定义 + 主键/外键/唯一/检查约束 + 索引及包含列 + 注释 + 可选 DDL

—

dm_query

只读 SELECT,绑定参数

—

dm_table_sample

采样看数据,自动处理标识符引号与大小写

—

dm_table_count

精确 COUNT(*)(也可用统计估算值)

—

dm_explain

执行计划

—

dm_search_objects

按关键字搜表名/列名/列注释(支持中文注释)

—

dm_execute_dml

INSERT / UPDATE / DELETE,结构化入参

DM_ALLOW_WRITE

dm_execute_ddl

CREATE / ALTER / DROP

DM_ALLOW_DDL

安全边界

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

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

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

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

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

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

永久禁止(任何开关状态下都不放行): TRUNCATE(DDL 语句;LISTAGG ... ON OVERFLOW TRUNCATE 溢出子句中的关键字不算,见 issue #1)、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)

160

DROP TABLE

139

INSERT

157

ALTER TABLE

146

UPDATE

159

TRUNCATE

194

DELETE

158

EXPLAIN

149

MERGE

164

COMMIT / ROLLBACK

147 / 148

CREATE TABLE

129

SET SCHEMA

153

CREATE VIEW / INDEX / SEQ

131 / 133 / 196

CALL / BEGIN / 多语句

162

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

标识符大小写

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

开发

git clone https://github.com/SpringDamon/mcp-server-dmdb.git
cd mcp-server-dmdb
npm install
npm run build      # tsc -> dist/
npm test           # 构建 + node --test 跑门禁用例(49 条)

下面两个脚本要连真实库,凭据只从环境变量读取,缺失即报错(见 scripts/env.mjs):

export DM_HOST=<host> DM_USER=<user> DM_PASSWORD=<pwd> DM_SCHEMA=<schema>
node scripts/probe-connect.mjs   # 验证数据库连通性
node scripts/verify-dict.mjs     # 导出字典视图真实列名
node scripts/e2e-mcp.mjs         # 端到端 JSON-RPC 验证(45 项检查)

依赖

运行时只有 3 个,刻意保持最小:

依赖

版本

说明

@modelcontextprotocol/server

^2.0.0

MCP SDK v2,ESM-only。协议细节见上文「支持的 MCP 协议」

dmdb

1.0.52452

官方驱动,精确锁版本(非 semver,加 ^ 无意义)。CJS 包,只能用默认导入

zod

^4.5.2

schema 校验

开发依赖: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。

附录:字典视图真实列名

以下在真实 DM8 实例上实测所得,与 Oracle 文档有出入,勿照搬 Oracle 经验:

视图

关键列

ALL_TABLES

OWNER, TABLE_NAME, TABLESPACE_NAME, NUM_ROWS, BLOCKS, STATUS, LAST_ANALYZED

ALL_TAB_COLUMNS

OWNER, TABLE_NAME, COLUMN_NAME, DATA_TYPE, DATA_LENGTH, DATA_PRECISION, DATA_SCALE, NULLABLE, COLUMN_ID, DATA_DEFAULT

ALL_CONSTRAINTS

OWNER, CONSTRAINT_NAME, CONSTRAINT_TYPE(P/R/U/C), TABLE_NAME, SEARCH_CONDITION, R_OWNER, R_CONSTRAINT_NAME, STATUS

ALL_CONS_COLUMNS

OWNER, CONSTRAINT_NAME, TABLE_NAME, COLUMN_NAME, **POSITION**

ALL_INDEXES

OWNER, INDEX_NAME, INDEX_TYPE, TABLE_OWNER, TABLE_NAME, UNIQUENESS, STATUS

ALL_IND_COLUMNS

INDEX_OWNER, INDEX_NAME, TABLE_OWNER, TABLE_NAME, COLUMN_NAME, **COLUMN_POSITION**, DESCEND

ALL_TAB_COMMENTS

OWNER, TABLE_NAME, TABLE_TYPE, COMMENTS

ALL_COL_COMMENTS

OWNER, TABLE_NAME, SCHEMA_NAME, COLUMN_NAME, COMMENTS

ALL_USERS

USERNAME, USER_ID, CREATED

V$VERSION

BANNER

V$INSTANCE

NAME, INSTANCE_NAME, SVR_VERSION, DB_VERSION, START_TIME, STATUS$

注意不对称:索引位置列叫 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/               env.mjs(凭据校验)+ probe-connect / verify-dict / e2e-mcp

License

MIT

Available Tools

9 tools
dm_describe_table查看表结构A
Read-onlyIdempotent

返回一张表的完整结构:列定义(类型/长度/精度/可空/默认值)、主键、外键、唯一键、检查约束、索引及其包含的列、表注释与列注释,可选附带建表 DDL。写 SQL 之前调用它,避免猜列名和类型。注意:索引位置列在达梦里叫 COLUMN_POSITION,而约束位置列叫 POSITION,两者不同名。

Inputs: table (required), owner, include_ddl, response_format.

dm_explain查看 SQL 执行计划A
Read-onlyIdempotent

返回一条 SELECT 语句在达梦 DM8 上的执行计划(走 EXPLAIN FOR,达梦的裸 EXPLAIN 不返回结果集)。输出包含 OPERATION、TAB_NAME、IDX_NAME、SCAN_TYPE、ROW_NUMS、COST 等列。排查慢查询、确认有没有走索引时调用。只接受 SELECT;EXPLAIN 不支持绑定参数,传入的 params 会被内联为字面量(经转义)。

Inputs: sql (required), params, response_format.

dm_list_schemas列出可访问的数据库模式A
Read-onlyIdempotent

列出当前连接用户在达梦 DM8 中可访问的全部模式(schema/用户)。不确定某个表属于哪个 schema、或想确认库里有哪些业务库时调用。主查询走 ALL_USERS;若权限不足会退回 SYSOBJECTS 按 TYPE$='SCH' 查询。

Inputs: response_format. Returns: count, schemas

dm_list_tables列出达梦中的表A
Read-onlyIdempotent

按模式名和表名关键字列出达梦 DM8 中的表,附带行数统计、所在表空间和表注释。用于"这个库里有哪些表""我要找订单相关的表"这类探索。注意 NUM_ROWS 来自统计信息,本库多数表未收集统计信息因而为 NULL;需要准确行数请用 dm_table_count 做精确 COUNT。标识符不区分大小写,传 order 或 ORDER 都可以。

Inputs: limit, owner, offset, pattern, +1 more.

dm_ping检查达梦连接与权限开关A
Read-onlyIdempotent

检查到达梦 DM8 数据库的连接是否正常,返回服务端版本、实例名、当前连接用户,以及 DM_ALLOW_WRITE / DM_ALLOW_DDL 两个写权限开关的当前状态。排查"连不上"或"提示没有写权限"时先调用本工具。本工具只读取会话与实例元数据,不查询任何业务表。

Inputs: no named parameters. Returns: connected, startTime, ddlEnabled, currentUser, +4 more

dm_query执行只读 SELECT 查询A
Read-onlyIdempotent

在达梦 DM8 上执行一条 SELECT 语句,返回列名与结果行。只放行 SELECT:INSERT/UPDATE/DELETE/DDL/多语句/存储过程调用都会被拒绝。分页请在 SQL 里写 LIMIT ? OFFSET ? 并把数值放进 params(DM8 原生支持绑定参数,已实测)。结果会自动按行数、单元格长度、总字符数三层截断,截断提示里会给出下一步建议。BIGINT 主键超出 JS 安全整数范围时会自动改用字符串重读,保证末几位不丢。

Inputs: sql (required), params, max_rows, timeout_ms, +1 more.

dm_search_objects按关键字搜索表和列A
Read-onlyIdempotent

按关键字跨表搜索:表名、列名、列注释三处任一命中即返回,同时给出所属表、列类型和注释。适合"哪个表里有手机号字段""跟退款相关的列在哪"这类探索。中文注释也能搜(例如搜"订单")。

Inputs: keyword (required), limit, owner, offset, +1 more.

dm_table_count统计表行数A
Read-onlyIdempotent

返回一张表的行数。默认执行精确 COUNT(*)。注意:达梦 ALL_TABLES.NUM_ROWS 来自统计信息,本库多数表未收集统计信息,该值通常为 NULL —— 所以不要拿 dm_list_tables 里的 NUM_ROWS 当真实行数,要用本工具。大表可以把 exact 设为 false,只读取统计估算值(可能不可用)。

Inputs: table (required), exact, owner, response_format. Returns: table, exactCount, lastAnalyzed, estimatedRows

dm_table_sample采样查看表数据A
Read-onlyIdempotent

从指定表取几行样本数据,省去手写 SELECT 的步骤,也不用处理标识符大小写和引号。想快速了解一张表里"数据长什么样"时用这个;需要条件过滤或聚合请用 dm_query。默认只取 5 行,避免把上下文打满。

Inputs: table (required), limit, owner, offset, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Every tool has a clearly distinct role: ping for connectivity, list_schemas, list_tables, describe_table, query, sample, count, explain, and search_objects. Even the overlapping conveniences (sample/count vs query) are explicitly differentiated by purpose and usage guidance.

    Naming Consistency4/5

    All tools share the dm_ prefix and use snake_case, but word order varies slightly: list_schemas/list_tables/describe_table/search_objects are action-first, while table_sample/table_count are object-first. The prefix makes the set predictable and readable despite the minor inconsistency.

    Tool Count5/5

    Nine tools is well-scoped for a DM8 database exploration/query server. Each tool addresses a distinct operation without bloat, covering connection checks, metadata discovery, querying, sampling, counts, and execution plans.

    Completeness5/5

    For a read-only database toolset, the surface is complete: connection validation, schema/table discovery, detailed schema inspection, free-form SELECT, quick sampling, exact counts, EXPLAIN, and cross-object search. No obvious dead ends or missing operations within the stated domain.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a lightweight MySQL database interface via stdio, enabling query execution, data manipulation, schema inspection, and connection testing using FastMCP tools.
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides table structure browsing and read-only query capabilities for DM8 databases, enabling interaction through MCP clients like Claude Desktop.
      3
      10
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      Multi-database management tool and MCP server supporting MySQL, PostgreSQL, SQLite, and Dameng DM8, enabling AI assistants to query and manage databases via stdio or HTTP.
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A multi-database MCP tool that enables LLM agents to securely query and write to databases via local stdio, supporting MySQL, Oracle, PostgreSQL, DM, SQLite and more.
      1
      -