DexSQL 数据查询 lolkda/dsh-dexsql-mcp

@lolkda/dsh-dexsql-mcp

一个 DeepSeek Harness 插件包，借助官方 @deepseek-ai/dsh-mcp-client Host 插件，把 DexSQL 接入 DSH。

npm 上发布的包包含：

- DSH 插件包配置；
- 一个小型启动器；
- 六个受支持平台各自的 DexSQL 二进制文件。

安装这个插件包就是全部安装步骤。不需要单独安装 dexsql，不需要往全局 PATH 里加条目，也不需要在运行时下载。

git 检出只保留配置，并标记为 private。发布构建会从上游下载编译好的二进制文件，校验其校验和，再打进 npm tarball 一起发布。

环境要求

- DSH：运行时清单不限定版本；开发与发布验收基线为 0.2.1-rc.2（更新版本需重新做真实宿主回归）
- 满足以下平台之一：
- Linux x64 或 arm64（glibc）
- macOS x64 或 arm64
- Windows x64 或 arm64
- npm tarball 约 62MB，解压后约 132MB，因为打包了所有平台

安装

dsh plugin --profile web add @lolkda/dsh-dexsql-mcp

也可以用 Web UI：插件 → 添加插件，然后输入 @lolkda/dsh-dexsql-mcp。

包内声明了 dsh.bundle.patch，所以 dsh plugin add 会自动把它注册到 dsh.profile.bundles。加载后，插件包插入一行：

dexsql-mcp -> @deepseek-ai/dsh-mcp-client

MCP 工具以 mcp__dexsql__ 的形式暴露。

使用

连接成功后，服务器暴露以下工具：

- open_dataset、list_datasets、close_dataset
- list_tables、describe_table、query
- decode、get_manifest、get_manifest_components
- list_resource_files、read_resource、query_resources

典型的首次调用：

Use mcp__dexsql__open_dataset with the absolute path to an APK or DEX file,
then mcp__dexsql__query against the returned dataset_id.

配置

默认连接配置在 cordis.patch.yml：

- insert:
- id: dexsql-mcp
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: dexsql
transport: stdio
command: !!js process.execPath
args:
- !!js decodeURIComponent(new URL('./node_modules/@lolkda/dsh-dexsql-mcp/bin/dexsql.mjs', baseUrl).pathname).replace(/^\/([A-Za-z]:)/, '$1')
- mcp
- --timeout-ms
- "300000"
failOnStartupError: true
toolCallTimeoutMs: 300000
baseUrl 是配置档目录。这一行会在同一个配置档里，用 node_modules/@lolkda/dsh-dexsql-mcp/bin/dexsql.mjs 启动启动器，因此不需要全局的 dexsql。

failOnStartupError: true 会让启动器缺失或 DexSQL 二进制损坏的问题直接暴露出来，而不是悄悄丢掉工具。如果你更希望尽力启动，把它覆盖成 false。

想用外部的 dexsql 替代内置二进制，在配置档的 cordis.patch.yml 里覆盖这一行：

- id: dexsql-mcp
config:
command: /usr/local/bin/dexsql
args: [mcp, --timeout-ms, "300000"]

工作原理

@lolkda/dsh-dexsql-mcp (npm package)
-> cordis.patch.yml (DSH configuration)
-> @deepseek-ai/dsh-mcp-client (Host plugin)
-> node .../node_modules/@lolkda/dsh-dexsql-mcp/bin/dexsql.mjs mcp
-> vendor/<os>-<cpu>/dexsql[.exe]
-> registers mcp__dexsql__ tools

这个包复用官方 DSH MCP 客户端，由它负责工具注册、schema 处理、超时、重连行为和资源。

验证

单元测试：

npm install
npm test
npm run pack:check

同步与打包测试离线运行：

npm run test:sync

暂存一份真实的上游发布产物，但不发布：

npm run sync:dexsql -- --version 0.2.0 --out .build/npm
npm pack .build/npm/package --dry-run

暂存的包在 .build/npm/package 下；.build/npm/manifest.json 记录上游 tag、校验和，以及该发布是否已经打包过。

本地测试 DSH 时，请安装暂存的包，不要装源码检出，因为源码检出有意不带 vendor/ 二进制：

dsh plugin --profile test add .build/npm/package

MCP 集成测试是直接的二进制冒烟测试，只在 dexsql 位于 PATH 上时运行：

npm run test:mcp

它会针对 dexsql mcp 执行真实的 initialize + tools/list 握手。内置启动器路径由打包测试覆盖，发布前还应在临时 DSH 配置档里检查一遍。

查看组装后的 DSH 配置档：

dsh --profile web --dump-config | grep -A 12 dexsql-mcp

自动同步上游

publish.yml 在每次推送到 main、发布 release、手动触发时运行，另外每天按 Asia/Shanghai 时区在 08:17、12:17、18:17、22:17 运行四次。GitHub cron 用 UTC，所以工作流表达式是 17 0,4,10,14 * * *。

每次运行：

1. 从 LSPosed/dexsql-release 解析最新的稳定 release。
2. 要求六个平台的二进制、LICENSE、LICENSE-AUXILIARY 和 SHA256SUMS 齐全。
3. 下载资产并校验每个校验和。
4. 如果上游 LICENSE 不再是 DexSQL Binary License，或 LICENSE-AUXILIARY 不再是 MIT，就拒绝重新发布。
5. 检查最新已发布 npm 包的 dexsql.version。
6. 如果上游版本已经打包过，直接退出，不发布。
7. 否则构建一个 npm 包，包含启动器和全部六个二进制文件；需要时递增包的补丁版本号，再用 npm trusted publishing 发布。

包版本与上游 DexSQL 版本相互独立。上游版本记录在包的 dexsql.version 字段和 vendor/manifest.json 中。首个内置版本是 0.2.0，对应 DexSQL 0.1.1；之后的上游版本依次对应 0.2.1、0.2.2，以此类推。

手动触发支持指定 tag 和 dry run：

gh workflow run publish.yml -f dry_run=true
gh workflow run publish.yml -f tag=v0.1.1 -f dry_run=false

工作流从不提交二进制文件；它把二进制文件暂存到 .build/npm 下，再从 runner 发布。它使用 npm trusted publishing（id-token: write + --provenance），不使用 NPM_TOKEN secret。

要在已有配置档中接入新的上游版本，更新插件并重启：

dsh plugin --profile web add @lolkda/dsh-dexsql-mcp

配置档的 lockfile 会锁定已安装的包版本，所以新的 npm 版本不会自动生效。

发布

首次内置发布有两种方式：

- 创建 GitHub release v0.2.0；publish.yml 会从最新上游版本构建包并发布；
- 或者运行 gh workflow run publish.yml -f dry_run=false，让工作流自动选择下一个版本。

npm trusted publisher 必须按以下配置：

- repository: lolkda/dsh-dexsql-mcp
- workflow: publish.yml
- permission: allow publish

工作流只发布 .build/npm/package 下暂存的包 0.2.0（或之后自动选定的版本）；不发布单独的平台包。直接发布仓库根目录会被 private: true 有意阻止，因为该源码包不含二进制文件。

release tag 必须与 package.json 一致（0.2.0 对应 v0.2.0）。npm 上已存在的包版本会被工作流跳过。

安全

- npm 包内含一个小型 MIT 许可的 JavaScript 启动器，以及编译好的上游二进制文件和它们的许可证。
- 同步工作流在打包前会对照上游 SHA256SUMS 校验每个二进制文件和许可证，npm 发布 tarball 时附带 provenance。
- MCP 客户端以 DSH 宿主进程的权限启动启动器。
- 只打开你信任的 APK/DEX 文件。DexSQL 能读取该进程可访问的文件。
- DexSQL 二进制文件闭源，受 DexSQL Binary License 1.0 约束。本仓库只重新分发已发布的编译二进制文件，不包含引擎源码。

许可证

DSH bundle 和启动器采用 MIT。DexSQL 本身按 DexSQL Binary License 1.0 分发；见 DexSQL release repository。