dbatools-mcp-server

dbatools-mcp-server

为 dbatools PowerShell 模块提供的 Model Context Protocol (MCP) 服务。

将 dbatools 命令公开为 MCP 工具，让 AI 助手（GitHub Copilot、Claude 等）能够直接发现、说明和执行 dbatools 命令——所有元数据均来自 dbatools 自带的基于注释的帮助。

---

功能

• list_dbatools_commands — 按动词、名词、关键词或风险级别搜索命令
• get_dbatools_command_help — 获取来自 Get-Help -Full 的完整标准化帮助（摘要、参数、示例）
• invoke_dbatools_command — 执行任意 dbatools 命令，并提供安全的参数验证、风险控制和结构化 JSON 输出
• check_dbatools_environment — 验证 PowerShell 和 dbatools 的安装情况、索引新鲜度以及版本一致性
• 工具注解 — 每个工具都会声明 readOnlyHint / destructiveHint / idempotentHint / openWorldHint，让 MCP 客户端（例如 VS Code）能在调用工具前于 UI 中显示风险
• 资源 — 浏览 dbatools://command/{name}，以结构化 JSON 格式读取任意命令的完整标准化帮助，不受面向对话的工具响应限制
• 持久 PowerShell 会话 — invoke_dbatools_command 会重用一个长期运行且已预导入 dbatools 的 pwsh 进程，而不是每次调用都启动新进程并重新导入 dbatools
• 版本不匹配检测 — 当已安装的 dbatools 版本与索引版本不同时发出警告
• 安全模式 — 执行非只读命令需要显式设置 confirm: true
• SQL 身份验证支持 — 为 SQL 身份验证实例传入 SqlCredential: { username, password }

---

前置条件

• Node.js 20+
• PowerShell 7+（pwsh）
• dbatools PowerShell 模块

Install-Module dbatools -Scope CurrentUser

---

快速开始

# 1. Clone the repo
git clone https://github.com/Dataplat/dbatools-mcp-server.git
cd dbatools-mcp-server

# 2. Install Node dependencies
npm install

# 3. Generate the help index from your local dbatools installation
npm run refresh-help

# 4. Build
npm run build

然后在 VS Code 中打开该文件夹——.vscode/mcp.json 文件会自动注册 MCP 服务。

---

连接到 VS Code

附带的 .vscode/mcp.json 会将该服务注册为本地 STDIO MCP 服务。 在 VS Code 中打开此文件夹，服务便会显示在 GitHub Copilot MCP 面板中。

{
  "servers": {
    "dbatools": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/server.js"],
      "env": {
        "DBATOOLS_SAFE_MODE": "true",
        "MAX_OUTPUT_ROWS": "100",
        "COMMAND_TIMEOUT_SECONDS": "60"
      }
    }
  }
}

---

配置

所有设置均通过环境变量控制（在 .vscode/mcp.json 或 shell 中设置）：

变量	默认值	说明
PWSH_EXE	pwsh	PowerShell 可执行文件的路径
DBATOOLS_SAFE_MODE	true	当值为 true 时，执行非只读命令需要设置 confirm: true
MAX_OUTPUT_ROWS	100	每次命令执行最多返回的行数
COMMAND_TIMEOUT_SECONDS	60	终止 PowerShell 进程前等待的秒数
DBATOOLS_PERSISTENT_SESSION	true	当值为 true 时，invoke_dbatools_command 会重用一个长期运行且已预导入 dbatools 的 PowerShell 进程，而不是每次调用都启动新进程。设为 false 可强制每次调用都启动新进程。

---

刷新帮助索引

帮助索引（generated/dbatools-help.json）根据本地安装的 dbatools 模块生成。 每当 dbatools 更新后，请重新运行：

Update-Module dbatools -Scope CurrentUser
npm run refresh-help

服务会在运行时检测版本不匹配，并在索引过期时发出警告。

---

风险级别

命令会根据动词自动分类：

风险级别	动词	行为
readonly	Get、Test、Find、Compare、…	始终允许
change	Set、New、Add、Copy、Enable、…	安全模式下需要 confirm: true
destructive	Remove、Drop、Disable、Reset、…	安全模式下需要 confirm: true

每个风险级别都对应标准的 MCP 工具注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），因此兼容的客户端可以在调用工具前于 UI 中显示风险。invoke_dbatools_command 是一个可运行任何命令的通用分发器，因此其注解会保守地反映最坏情况（destructiveHint: true）——实际的单条命令风险仍由运行时的安全模式门控机制强制执行。

---

资源

除了四个工具之外，服务还将每条已索引命令作为 MCP 资源公开，地址为 dbatools://command/{name}（例如 dbatools://command/Get-DbaDatabase），并以结构化 JSON 的形式返回相同的规范化帮助记录——这对浏览或基于资源获取信息，而非调用工具的客户端很有用。可浏览的资源列表不包含 PowerShell 别名（例如 Attach-DbaDatabase，它是 Mount-DbaDatabase 的别名），因为这些别名只会转发到另一个命令的帮助信息。

---

持久 PowerShell 会话

默认情况下，invoke_dbatools_command 会复用一个长期运行且已预先导入 dbatools 的 pwsh 进程，而不是每次调用都启动新进程（并重新导入 dbatools）。这样，首次调用之后的每次调用都无需承担约 1–2 秒甚至更久的进程启动和模块导入开销。

有几点需要注意：

• 崩溃／超时恢复：如果命令超时或会话进程崩溃，进程会被终止并丢弃；下一次调用会自动启动新会话（并再次承担一次导入开销）。触发故障的调用不会自动重试。
• 跨调用状态：dbatools 会在 PowerShell 会话中缓存某些状态（例如通过 Connect-DbaInstance 建立的 SMO 连接）。使用持久会话后，这些缓存现在会在一次 MCP 服务运行期间的多次工具调用间共享；此前每次调用都是完全隔离的。每个独立脚本仍会在自己的作用域中运行，因此普通变量不会在调用间泄漏——受影响的只有 dbatools 自身的内部缓存行为。

设置 DBATOOLS_PERSISTENT_SESSION=false 可禁用此功能，恢复为每次调用都启动一个新进程。

---

SQL 身份验证

对于仅支持 SQL 身份验证的实例（例如 Docker），请通过 SqlCredential 参数传递凭据：

{
  "SqlInstance": "localhost,1433",
  "SqlCredential": { "username": "<SqlLogin>", "password": "YourPassword" }
}

---

项目结构

dbatools-mcp-server/
├── src/
│   ├── server.ts              # MCP server entry point, tool/resource definitions
│   ├── powershell.ts           # One-shot PowerShell process runner, health checks, version detection
│   ├── powershell-session.ts   # Persistent PowerShell session (long-lived process, dbatools pre-imported)
│   ├── help-indexer.ts         # Help manifest loader and command search
│   ├── tool-registry.ts        # Risk classification, tool annotations, safe argument builder
│   └── types.ts                # Shared TypeScript interfaces
├── scripts/
│   └── refresh-help.ps1       # Generates generated/dbatools-help.json
├── generated/                 # Help index (gitignored, generated locally)
├── .vscode/
│   └── mcp.json               # VS Code MCP local server registration
└── dist/                      # Compiled output (gitignored)

---

贡献

欢迎贡献！对于重大更改，请先提交 issue。

本项目秉承与 dbatools 相同的社区精神。

---

许可证

MIT — © 2026 DataPlat 贡献者