mcp-sql

CLI 工具 / MCP 服务器，用于通过模型上下文协议（Model Context Protocol）连接 SQL Server。

Isasoft SAS 版权所有。

安装依赖

bun install

开发

直接使用 Bun 运行（开发模式）：

bun run src/cli.ts --help

构建独立可执行文件

编译为单个原生可执行文件，目标机器上无需 Bun/Node 运行时：

bun run build:win        # dist/mcp-sql-win-x64.exe (Windows x64)

还提供了交叉编译脚本（未作为本构建的一部分运行/验证，但 build:linux 已在 Windows 上成功交叉编译；build:mac-x64 / build:mac-arm64 尚未在真实 macOS 硬件上验证）：

bun run build:mac-x64    # dist/mcp-sql-macos-x64 (macOS Intel, cross-compiled, unverified)
bun run build:mac-arm64  # dist/mcp-sql-macos-arm64 (macOS Apple Silicon, cross-compiled, unverified)
bun run build:linux      # dist/mcp-sql-linux-x64 (Linux x64, cross-compiled)

输出二进制文件写入 dist/。

用法

构建完成后（或在开发模式下通过 bun run src/cli.ts），CLI 提供以下子命令：

mcp-sql setup [name]  Interactively configure a SQL Server connection
                       (defaults to the name "default")
mcp-sql list           List configured connections and mark the active one
mcp-sql use <name>     Switch which configured connection is active
mcp-sql remove <name>  Remove a configured connection (and its credential)
mcp-sql run            Run mcp-sql in server mode (starts the MCP server)
mcp-sql discover        Detect installed AI clients (Claude Desktop, Cline, Roo
                        Code) and configure them to use mcp-sql

多个连接

mcp-sql 可以同时存储多个命名的 SQL Server 连接，但任何时刻只有一个是活动的——mcp-sql run（以及任何连接的 AI 客户端）使用的就是这一个。如果你从不显式传入名称，一切行为与之前完全相同，名称默认为 "default"。

setup

mcp-sql setup          # configure (or reconfigure) the "default" connection
mcp-sql setup staging  # configure a connection named "staging"

通过交互式向导引导你配置并存储指定名称下的 SQL Server 连接详情/凭据（省略时默认为 default）。最后会询问该连接是否应成为活动连接（如果是你配置的第一个连接，默认值为"是"）。

list

mcp-sql list

列出所有已配置连接的名称及其主机和数据库（绝不显示密码），并标记哪个是活动连接。如果尚未配置任何连接，则打印一条清晰的消息（不会崩溃）。

use

mcp-sql use staging

将指定连接标记为活动。如果名称不存在，则打印清晰的错误信息以及已知连接名称列表。

remove

mcp-sql remove staging

删除已配置的连接及其存储的凭据。拒绝删除当前活动连接——请先使用 mcp-sql use <other-name> 切换到其他连接。

discover

mcp-sql discover           # detect clients and write/merge their MCP config
mcp-sql discover --dry-run # preview what would be written, without touching any files

检测已安装的 AI 客户端（Claude Desktop、Cline、Roo Code），并将 mcp-sql 条目注入每个客户端的 MCP 配置文件中，指向此可执行文件自身的路径（command），参数为 args: ["run"]。保留现有配置内容和其他 MCP 服务器条目；每次实际（非试运行）注入时都会写入先前文件的 .bak 备份。

run

mcp-sql run

以 MCP 服务器模式启动 mcp-sql。这是 AI 客户端调用的方式——你通常不需要手动运行它；discover 会为你配置好。

永久安装位置

discover 将当前运行的可执行文件的绝对路径（process.execPath）注入每个客户端的配置。这意味着编译后的 .exe 在对其运行 discover 后必须保持原位——如果之后移动或重命名它，客户端配置将指向一个不再存在的文件。

建议：将编译后的可执行文件保留在

C:\Users\Wil\appisoft\mcp\dist\mcp-sql-win-x64.exe

即 bun run build:win 生成它的位置，位于这个稳定的项目目录内。

运行 discover 后不要移动此文件。 如果确实需要移动它，请从可执行文件的新位置重新运行 discover（例如 path\to\new\location\mcp-sql-win-x64.exe discover）以更新客户端配置。

安装 / 分发

发布版本由 azure-pipelines.yml 中定义的 Azure Pipelines 管道自动构建：

1. 推送匹配 v* 的标签（例如 v1.0.0）。管道在标签推送时触发（或可手动运行），安装 Bun，运行 bun test 和 bunx tsc --noEmit 作为硬性门禁，然后在单个 windows-latest 代理上运行全部 4 个 bun run build:* 脚本（Bun 从 Windows 交叉编译 mac/linux 目标；目前只有 build:win 和 build:linux 经过运行验证——mac 构建在真实硬件上为尽力而为/未验证，见上方说明）。

2. 所有 4 个二进制文件的 SHA256 校验和生成到 dist/checksums.sha256。

3. 所有内容（4 个二进制文件、安装脚本和校验和文件）作为名为 mcp-sql-release 的 Azure DevOps 管道工件发布。从管道运行的"工件"（Artifacts）选项卡下载。（管道中注释掉的 GitHubRelease@1 块展示了在配置 GitHub 服务连接后如何同时发布到 GitHub Release。）

最终用户随后从下载的 mcp-sql-release 文件夹内使用单个脚本安装：

# Windows
.\install.ps1

# macOS / Linux
./install.sh

两个脚本都会安装二进制文件，可选运行 mcp-sql setup（交互式凭据向导）和 mcp-sql discover（配置 Claude Desktop、Cline、Roo Code），并在触碰任何其他应用程序的配置文件之前明确打印将要执行的操作。传入 -SkipSetup/-SkipDiscover（PowerShell）或 --skip-setup/--skip-discover（bash）可退出自动步骤。

本仓库的 /docs 文件夹已准备好作为项目的 Wiki 发布到 Azure DevOps（项目设置 -> Wiki -> 将代码发布为 wiki -> 此仓库 -> /docs）。其中包含一份"一行命令"风格的安装指南（适配 Azure Artifacts 私有源）——参见 docs/Installation.md。

另外（或同时），一旦此仓库托管在 GitHub 上，同一个 /docs 文件夹可以通过 GitHub Pages 发布：启用 设置 -> Pages -> 源："GitHub Actions"（仅需一次），然后 .github/workflows/pages.yml 工作流会在每次触及 docs/** 的 main 推送时自动构建并部署 docs/（通过 Jekyll）。

署名

"Propiedad de Isasoft SAS" 会作为 mcp-sql --help 输出的一部分打印。