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 — 安全なパラメーター検証、リスク制御、構造化 JSON 出力により、任意の dbatools コマンドを実行します
• check_dbatools_environment — PowerShell と dbatools のインストール状況、インデックスの鮮度、バージョンの整合性を確認します
• ツールアノテーション — 各ツールは readOnlyHint / destructiveHint / idempotentHint / openWorldHint を宣言するため、MCP クライアント（VS Code など）はツールが呼び出される前に、UI 上でリスクを提示できます
• リソース — dbatools://command/{name} を参照すると、チャット向けのツール応答とは独立して、任意のコマンドの正規化済み完全なヘルプを構造化 JSON として確認できます
• 永続 PowerShell セッション — invoke_dbatools_command は呼び出しごとに新しいプロセスを起動して dbatools を再インポートする代わりに、dbatools を事前にインポートした、長時間稼働する単一の pwsh プロセスを再利用します
• バージョン不一致の検出 — インストール済みの 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 またはシェルで設定します）。

変数	デフォルト	説明
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）が反映されます。実際のコマンドごとのリスクは、引き続きセーフモードのゲートによって実行時に適用されます。

---

リソース

4 つのツールに加えて、サーバーはインデックス化されたすべてのコマンドを dbatools://command/{name}（例：dbatools://command/Get-DbaDatabase）の MCP リソースとして公開し、構造化 JSON 形式で同じ正規化済みヘルプレコードを返します。ツールを呼び出すのではなく、リソースを参照したり、それを根拠として利用したりするクライアントに便利です。参照可能なリソース一覧には PowerShell のエイリアス（例：Mount-DbaDatabase のエイリアスである Attach-DbaDatabase）は含まれません。これらは別のコマンドのヘルプに処理を転送するだけだからです。

---

永続的な PowerShell セッション

デフォルトでは、invoke_dbatools_command は呼び出しのたびに新しいプロセスを起動して dbatools を再インポートするのではなく、dbatools を事前にインポートした単一の長時間実行 pwsh プロセスを再利用します。これにより、初回以降の各呼び出しで発生していた約 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 のコントリビューター