taf-mysql-mcp

给 AI agent 用的 MySQL 查询 MCP server：通过 TAF 的 TgDataAsync 数据访问服务转发 SQL，默认只读，DDL 无条件禁止。

不需要本机装 mysql 客户端，也不需要数据库账号密码——走的就是你业务服务已经在用的那条 TAF 通道。

安装

npm install -g @bobjoy/taf-mysql-mcp

命令名不带 scope，装完就是 taf-mysql-mcp。

依赖 @taf/taf-rpc / @taf/taf-stream，这两个包只在公司私有 npm 源上。装不上时先确认 @taf scope 指向了私有源：

npm config get @taf:registry

Related MCP server: MySQL ReadOnly MCP Server

配置

默认读 <cwd>/.taf-mysql-mcp/config.json，也可以指定别的文件：

taf-mysql-mcp --config /path/to/config.json
taf-mysql-mcp /path/to/config.json     # 裸路径同样接受，~ 会展开

除了这一个文件（或 --config 给的那一个）没有第二个来源：不读环境变量，不内置地址，参数打错（--confg）直接报错退出而不是静默回落到默认路径。文件不在、JSON 坏掉、字段类型不对都会退出并带上路径；未知的键只告警不生效。

{
  "servant": "<应用名>.TgDataAsyncServer.TgDataAsyncObj@tcp -h <host> -t 60000 -p <port>",
  "allowWrite": false,
  "maxRows": 200,
  "timeoutMs": 30000
}

servant 必须是 <应用名>.TgDataAsyncServer.TgDataAsyncObj@tcp -h <host> -p <port> -t 60000 这种完整值，只给 endpoint 不够。本工具不猜应用名、不内置任何地址、也不提供默认环境——避免本意连测试库实际连上了生产。

注册到 MCP 客户端

{
  "mcpServers": {
    "taf-mysql": {
      "command": "taf-mysql-mcp",
      "args": []
    }
  }
}

配置不进这段 JSON，只进文件。用默认路径时注意 cwd 是 MCP 客户端决定的，不是你敲命令的目录；想固定住就把路径写进 args：

{ "args": ["--config", "/path/to/config.json"] }

不确定实际读了哪个文件，看启动时 stderr 上那行 [config] 已读取 <绝对路径> ...。

工具面

只有一个工具 query(sql)，一次一条 SQL，结尾分号可省。跨库查询写全限定表名 <库名>.<表名>。

安全边界

• 默认只读。

• allowWrite: true 才放开 DML（INSERT / UPDATE / DELETE / REPLACE）。

• DDL 永远拒绝：TRUNCATE / DROP / ALTER / CREATE / RENAME / GRANT 等，开了写开关也救不了。

• 判定不是看首关键字：先把字符串字面量、反引号标识符、注释替换成等长占位，再按括号深度取真正的语句动词。所以 SELECT 'x; DROP TABLE t'、SELECT 1; DROP TABLE t、/*comment*/ DELETE ...、WITH d AS (...) DELETE ... 都不会骗过去。

• SELECT ... INTO OUTFILE / DUMPFILE 拒绝（能把数据写到服务端磁盘）。

• /*! ... */ 可执行注释拒绝（MySQL 会执行它，等于绕过判定）。

这个数据访问服务的实测行为

几条容易踩的，都是实测结论：

• 只支持 SELECT 族语句。SHOW TABLES / DESC 表名 / EXPLAIN 不会报错，而是返回 result: "false"，看起来像成功。本工具会把它识别出来并报成明确的失败，同时提示改用 information_schema：

  select table_name from information_schema.tables where table_schema = database();
  select column_name, data_type from information_schema.columns where table_name = '<表名>';

• SQL 本身报错时 iRet = -9999，error 里就是 MySQL 原始错误（Table 'xxx' doesn't exist 这类）。这是查询失败，不是网络失败。

• servant 地址或对象名配错时，TAF 客户端会一直挂到它自己的 60s 超时才 reject（-13001 call remote server timeout）。所以才有 timeoutMs 兜底，别指望它自动快速失败。

• 底层 @taf/taf-rpc 会在初始化和后台 endpoint 刷新时 console.log 到 stdout，而 stdio transport 的行分隔 JSON-RPC 一旦被非 JSON 行污染就整体失效。本工具在 require 它之前把 log/info/debug/warn 全部改道到 stderr，日志前缀 [taf]。

开发

npm test          # node --test，无额外依赖

sql-policy.test.js 是绕过用例集（注释、字面量、多语句、CTE 修饰的 DML、可执行注释、权限/事务/存储过程语句）；config.test.js 覆盖配置文件的读取路径、缺文件、坏 JSON、未知键告警与字段校验。改策略逻辑请先在这里加用例。