dbatools-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DataPlat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# dbatools-mcp-server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the [dbatools](https://dbatools.io) PowerShell module.
+
+Exposes dbatools commands as MCP tools so AI assistants (GitHub Copilot, Claude, etc.) can discover, explain, and execute dbatools commands directly — with all metadata sourced from dbatools' own **comment-based help**.
+
+---
+
+## Features
+
+- **`list_dbatools_commands`** — search commands by verb, noun, keyword, or risk level
+- **`get_dbatools_command_help`** — full normalized help (synopsis, parameters, examples) from `Get-Help -Full`
+- **`invoke_dbatools_command`** — execute any dbatools command with safe parameter validation, risk gating, and structured JSON output
+- **`check_dbatools_environment`** — verify PowerShell + dbatools installation, index freshness, and version alignment
+- **Version mismatch detection** — warns when installed dbatools version differs from the indexed version
+- **Safe mode** — non-readonly commands require explicit `confirm: true` to execute
+- **SQL Authentication support** — pass `SqlCredential: { username, password }` for SQL auth instances
+
+---
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20+
+- [PowerShell 7+](https://github.com/PowerShell/PowerShell/releases) (`pwsh`)
+- [dbatools](https://dbatools.io/download) PowerShell module
+
+```powershell
+Install-Module dbatools -Scope CurrentUser
+```
+
+---
+
+## Quick Start
+
+```powershell
+# 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
+```
+
+Then open the folder in VS Code — the `.vscode/mcp.json` file automatically registers the MCP server.
+
+---
+
+## Connecting to VS Code
+
+The included [`.vscode/mcp.json`](.vscode/mcp.json) registers the server as a local STDIO MCP server.
+Open this folder in VS Code and the server will appear in the GitHub Copilot MCP panel.
+
+```json
+{
+  "servers": {
+    "dbatools": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/dist/server.js"],
+      "env": {
+        "DBATOOLS_SAFE_MODE": "true",
+        "MAX_OUTPUT_ROWS": "100",
+        "COMMAND_TIMEOUT_SECONDS": "60"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Configuration
+
+All settings are controlled via environment variables (set in `.vscode/mcp.json` or your shell):
+
+| Variable | Default | Description |
+|---|---|---|
+| `PWSH_EXE` | `pwsh` | Path to PowerShell executable |
+| `DBATOOLS_SAFE_MODE` | `true` | When `true`, non-readonly commands require `confirm: true` |
+| `MAX_OUTPUT_ROWS` | `100` | Maximum rows returned per command execution |
+| `COMMAND_TIMEOUT_SECONDS` | `60` | Seconds before PowerShell process is killed |
+
+---
+
+## Refreshing the Help Index
+
+The help index (`generated/dbatools-help.json`) is generated from your locally installed dbatools module.
+Re-run whenever dbatools is updated:
+
+```powershell
+Update-Module dbatools -Scope CurrentUser
+npm run refresh-help
+```
+
+The server detects version mismatches at runtime and warns you when the index is stale.
+
+---
+
+## Risk Levels
+
+Commands are automatically classified by verb:
+
+| Risk Level | Verbs | Behavior |
+|---|---|---|
+| `readonly` | Get, Test, Find, Compare, … | Always allowed |
+| `change` | Set, New, Add, Copy, Enable, … | Requires `confirm: true` in safe mode |
+| `destructive` | Remove, Drop, Disable, Reset, … | Requires `confirm: true` in safe mode |
+
+---
+
+## SQL Authentication
+
+For SQL-auth-only instances (e.g. Docker), pass credentials via the `SqlCredential` parameter:
+
+```json
+{
+  "SqlInstance": "localhost,1433",
+  "SqlCredential": { "username": "<SqlLogin>", "password": "YourPassword" }
+}
+```
+
+---
+
+## Project Structure
+
+```
+dbatools-mcp-server/
+├── src/
+│   ├── server.ts          # MCP server entry point, tool definitions
+│   ├── powershell.ts      # PowerShell process runner, health checks, version detection
+│   ├── help-indexer.ts    # Help manifest loader and command search
+│   ├── tool-registry.ts   # Risk classification, 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)
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue first for significant changes.
+
+This project follows the same community spirit as [dbatools](https://github.com/dataplat/dbatools).
+
+---
+
+## License
+
+[MIT](LICENSE) — © 2026 DataPlat contributors

package/dist/help-indexer.d.ts

@@ -0,0 +1,21 @@
+import type { HelpIndex, HelpManifest, DbatoolsCommandHelp } from "./types.js";
+/**
+ * Load and cache the help manifest from generated/dbatools-help.json.
+ * Throws an actionable error if the file has not been generated yet.
+ */
+export declare function loadHelpManifest(): HelpManifest;
+/** Shorthand to get just the commands map from the manifest. */
+export declare function loadHelpIndex(): HelpIndex;
+export interface SearchOptions {
+    verb?: string;
+    noun?: string;
+    keyword?: string;
+    riskLevel?: string;
+    limit?: number;
+}
+/**
+ * Filter the help index with optional verb / noun / keyword / riskLevel filters.
+ * Keyword matches against name, synopsis, and description (case-insensitive).
+ */
+export declare function searchCommands(index: HelpIndex, opts: SearchOptions): DbatoolsCommandHelp[];
+//# sourceMappingURL=help-indexer.d.ts.map

package/dist/help-indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-indexer.d.ts","sourceRoot":"","sources":["../src/help-indexer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAO/E;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,YAAY,CAa/C;AAED,gEAAgE;AAChE,wBAAgB,aAAa,IAAI,SAAS,CAEzC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,aAAa,GAClB,mBAAmB,EAAE,CA6BvB"}

package/dist/help-indexer.js

@@ -0,0 +1,52 @@
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HELP_INDEX_PATH = join(__dirname, "../generated/dbatools-help.json");
+let cachedManifest = null;
+/**
+ * Load and cache the help manifest from generated/dbatools-help.json.
+ * Throws an actionable error if the file has not been generated yet.
+ */
+export function loadHelpManifest() {
+    if (cachedManifest)
+        return cachedManifest;
+    if (!existsSync(HELP_INDEX_PATH)) {
+        throw new Error(`Help index not found at: ${HELP_INDEX_PATH}\n` +
+            `Run 'npm run refresh-help' to generate it from your local dbatools installation.`);
+    }
+    const raw = readFileSync(HELP_INDEX_PATH, "utf-8");
+    cachedManifest = JSON.parse(raw);
+    return cachedManifest;
+}
+/** Shorthand to get just the commands map from the manifest. */
+export function loadHelpIndex() {
+    return loadHelpManifest().commands;
+}
+/**
+ * Filter the help index with optional verb / noun / keyword / riskLevel filters.
+ * Keyword matches against name, synopsis, and description (case-insensitive).
+ */
+export function searchCommands(index, opts) {
+    let commands = Object.values(index);
+    if (opts.verb) {
+        const v = opts.verb.toLowerCase();
+        commands = commands.filter((c) => c.verb.toLowerCase() === v);
+    }
+    if (opts.noun) {
+        const n = opts.noun.toLowerCase();
+        commands = commands.filter((c) => c.noun.toLowerCase().includes(n));
+    }
+    if (opts.keyword) {
+        const kw = opts.keyword.toLowerCase();
+        commands = commands.filter((c) => c.name.toLowerCase().includes(kw) ||
+            c.synopsis.toLowerCase().includes(kw) ||
+            c.description.toLowerCase().includes(kw) ||
+            c.tags.some((t) => t.toLowerCase().includes(kw)));
+    }
+    if (opts.riskLevel) {
+        commands = commands.filter((c) => c.riskLevel === opts.riskLevel);
+    }
+    return commands.slice(0, opts.limit ?? 50);
+}
+//# sourceMappingURL=help-indexer.js.map

package/dist/help-indexer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-indexer.js","sourceRoot":"","sources":["../src/help-indexer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAGpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,iCAAiC,CAAC,CAAC;AAE3E,IAAI,cAAc,GAAwB,IAAI,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,cAAc;QAAE,OAAO,cAAc,CAAC;IAE1C,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,4BAA4B,eAAe,IAAI;YAC7C,kFAAkF,CACrF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IACnD,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAiB,CAAC;IACjD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,aAAa;IAC3B,OAAO,gBAAgB,EAAE,CAAC,QAAQ,CAAC;AACrC,CAAC;AAUD;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAgB,EAChB,IAAmB;IAEnB,IAAI,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEpC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAClC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAClC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACtC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CACxB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CACnD,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC;IACpE,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;AAC7C,CAAC"}

package/dist/powershell.d.ts

@@ -0,0 +1,34 @@
+import type { PowerShellResult, ServerConfig } from "./types.js";
+/**
+ * Resolve runtime configuration from environment variables with safe defaults.
+ * All values can be overridden without code changes.
+ */
+export declare function getConfig(): ServerConfig;
+/**
+ * Spawn a PowerShell process, run the given script, and collect stdout/stderr.
+ * Rejects only on process spawn failure; non-zero exit codes are resolved normally
+ * so the caller can inspect exitCode and stderr.
+ */
+export declare function runPowerShell(script: string, config: ServerConfig): Promise<PowerShellResult>;
+/**
+ * Quick health-check: verifies that PowerShell and the dbatools module are
+ * available on the current machine.
+ */
+export declare function checkDbatools(config: ServerConfig): Promise<{
+    ok: boolean;
+    version?: string;
+    error?: string;
+}>;
+export interface VersionMismatchResult {
+    installedVersion: string;
+    indexedVersion: string;
+    isStale: boolean;
+    message: string;
+}
+/**
+ * Compare the installed dbatools version against the version stored in the
+ * help-index manifest. Returns a structured result with a human-readable
+ * warning when the two differ.
+ */
+export declare function checkVersionMismatch(config: ServerConfig, indexedVersion: string): Promise<VersionMismatchResult>;
+//# sourceMappingURL=powershell.d.ts.map

package/dist/powershell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"powershell.d.ts","sourceRoot":"","sources":["../src/powershell.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsBjE;;;GAGG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAOxC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAgE3B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB5D;AAED,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,EACpB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,qBAAqB,CAAC,CAwBhC"}

package/dist/powershell.js

@@ -0,0 +1,137 @@
+import { spawn } from "child_process";
+/** Maximum total stdout+stderr bytes buffered per PowerShell invocation (10 MB). */
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+/**
+ * Parse an integer env var, falling back to `defaultVal` when the value is
+ * missing, non-numeric, or outside the given bounds.
+ */
+function parseIntEnv(key, defaultVal, min, max) {
+    const raw = process.env[key];
+    if (!raw)
+        return defaultVal;
+    const parsed = parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < min || parsed > max)
+        return defaultVal;
+    return parsed;
+}
+/**
+ * Resolve runtime configuration from environment variables with safe defaults.
+ * All values can be overridden without code changes.
+ */
+export function getConfig() {
+    return {
+        powershellExe: process.env["PWSH_EXE"] ?? "pwsh",
+        safeMode: process.env["DBATOOLS_SAFE_MODE"] !== "false",
+        maxOutputRows: parseIntEnv("MAX_OUTPUT_ROWS", 100, 1, 10_000),
+        commandTimeout: parseIntEnv("COMMAND_TIMEOUT_SECONDS", 60, 5, 3600),
+    };
+}
+/**
+ * Spawn a PowerShell process, run the given script, and collect stdout/stderr.
+ * Rejects only on process spawn failure; non-zero exit codes are resolved normally
+ * so the caller can inspect exitCode and stderr.
+ */
+export function runPowerShell(script, config) {
+    return new Promise((resolve, reject) => {
+        const pwsh = spawn(config.powershellExe, [
+            "-NonInteractive",
+            "-NoProfile",
+            "-NoLogo",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            script,
+        ], { shell: false });
+        let stdout = "";
+        let stderr = "";
+        let totalBytes = 0;
+        let settled = false;
+        function fail(err) {
+            if (settled)
+                return;
+            settled = true;
+            pwsh.kill("SIGKILL");
+            reject(err);
+        }
+        const timer = setTimeout(() => {
+            fail(new Error(`PowerShell process timed out after ${config.commandTimeout}s`));
+        }, config.commandTimeout * 1000);
+        pwsh.stdout.on("data", (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > MAX_BUFFER_BYTES) {
+                clearTimeout(timer);
+                fail(new Error(`PowerShell output exceeded the ${MAX_BUFFER_BYTES / 1024 / 1024} MB safety limit`));
+                return;
+            }
+            stdout += chunk.toString();
+        });
+        pwsh.stderr.on("data", (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > MAX_BUFFER_BYTES) {
+                clearTimeout(timer);
+                fail(new Error(`PowerShell output exceeded the ${MAX_BUFFER_BYTES / 1024 / 1024} MB safety limit`));
+                return;
+            }
+            stderr += chunk.toString();
+        });
+        pwsh.on("close", (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            resolve({ stdout, stderr, exitCode: code ?? 1 });
+        });
+        pwsh.on("error", (err) => {
+            clearTimeout(timer);
+            fail(new Error(`Failed to launch '${config.powershellExe}': ${err.message}`));
+        });
+    });
+}
+/**
+ * Quick health-check: verifies that PowerShell and the dbatools module are
+ * available on the current machine.
+ */
+export async function checkDbatools(config) {
+    try {
+        const result = await runPowerShell(`$m = Get-Module -ListAvailable -Name dbatools | ` +
+            `Sort-Object Version -Descending | Select-Object -First 1; ` +
+            `if ($m) { Write-Output $m.Version.ToString() } else { exit 1 }`, config);
+        if (result.exitCode === 0 && result.stdout.trim()) {
+            return { ok: true, version: result.stdout.trim() };
+        }
+        return {
+            ok: false,
+            error: "dbatools module not found. Install it with: Install-Module dbatools -Scope CurrentUser",
+        };
+    }
+    catch (e) {
+        return { ok: false, error: String(e) };
+    }
+}
+/**
+ * Compare the installed dbatools version against the version stored in the
+ * help-index manifest. Returns a structured result with a human-readable
+ * warning when the two differ.
+ */
+export async function checkVersionMismatch(config, indexedVersion) {
+    const check = await checkDbatools(config);
+    if (!check.ok || !check.version) {
+        return {
+            installedVersion: "unknown",
+            indexedVersion,
+            isStale: false,
+            message: check.error ?? "Could not determine installed dbatools version.",
+        };
+    }
+    const installed = check.version.trim();
+    const isStale = installed !== indexedVersion;
+    const message = isStale
+        ? `⚠️  dbatools version mismatch detected!\n` +
+            `   Installed : ${installed}\n` +
+            `   Index     : ${indexedVersion}\n` +
+            `   The help index is stale. Run 'npm run refresh-help' to rebuild it.\n` +
+            `   Until then, command metadata may be inaccurate for new/changed commands.`
+        : `✅ dbatools version matches index (${installed}).`;
+    return { installedVersion: installed, indexedVersion, isStale, message };
+}
+//# sourceMappingURL=powershell.js.map

package/dist/powershell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"powershell.js","sourceRoot":"","sources":["../src/powershell.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":""}

package/dist/server.js

@@ -0,0 +1,330 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadHelpIndex, loadHelpManifest, searchCommands } from "./help-indexer.js";
+import { runPowerShell, checkDbatools, getConfig, checkVersionMismatch } from "./powershell.js";
+import { buildPowerShellScript, } from "./tool-registry.js";
+const config = getConfig();
+// Version mismatch state — resolved once at startup, reused by tools
+let versionState = null;
+async function getVersionState() {
+    if (versionState)
+        return versionState;
+    try {
+        const manifest = loadHelpManifest();
+        versionState = await checkVersionMismatch(config, manifest.dbatoolsVersion);
+    }
+    catch {
+        versionState = {
+            installedVersion: "unknown",
+            indexedVersion: "unknown",
+            isStale: false,
+            message: "Help index not yet generated — run 'npm run refresh-help'.",
+        };
+    }
+    return versionState;
+}
+const server = new McpServer({
+    name: "dbatools-mcp-server",
+    version: "0.1.0",
+});
+// ---------------------------------------------------------------------------
+// Tool: list_dbatools_commands
+// ---------------------------------------------------------------------------
+server.tool("list_dbatools_commands", "Search and list dbatools commands. Filter by verb, noun, keyword, or risk level.", {
+    verb: z
+        .string()
+        .max(50)
+        .optional()
+        .describe("PowerShell verb (e.g. Get, Set, New, Remove, Test)"),
+    noun: z
+        .string()
+        .max(100)
+        .optional()
+        .describe("Noun fragment to match (e.g. Database, Login, AgentJob)"),
+    keyword: z
+        .string()
+        .max(200)
+        .optional()
+        .describe("Keyword to search in name, synopsis, and description"),
+    riskLevel: z
+        .enum(["readonly", "change", "destructive"])
+        .optional()
+        .describe("Filter by risk tier"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .default(50)
+        .describe("Maximum number of results (default 50, max 200)"),
+}, async ({ verb, noun, keyword, riskLevel, limit }) => {
+    const vs = await getVersionState();
+    const stalePrefix = vs.isStale ? vs.message + "\n\n" : "";
+    let index;
+    try {
+        index = loadHelpIndex();
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Help index unavailable: ${String(e)}` }], isError: true };
+    }
+    const results = searchCommands(index, { verb, noun, keyword, riskLevel, limit });
+    if (results.length === 0) {
+        return {
+            content: [
+                { type: "text", text: stalePrefix + "No commands found matching the given filters." },
+            ],
+        };
+    }
+    const header = `Found ${results.length} command(s):\n`;
+    const rows = results
+        .map((c) => `${c.name.padEnd(50)} [${c.riskLevel.padEnd(11)}]  ${(c.synopsis ?? "").substring(0, 80)}`)
+        .join("\n");
+    return { content: [{ type: "text", text: stalePrefix + header + rows }] };
+});
+// ---------------------------------------------------------------------------
+// Tool: get_dbatools_command_help
+// ---------------------------------------------------------------------------
+server.tool("get_dbatools_command_help", "Get the full normalized help for a specific dbatools command, including parameters and examples sourced from comment-based help.", {
+    commandName: z
+        .string()
+        .max(100)
+        .describe("Exact command name, e.g. Get-DbaDatabase"),
+}, async ({ commandName }) => {
+    const vs = await getVersionState();
+    const stalePrefix = vs.isStale ? vs.message + "\n\n" : "";
+    let index;
+    try {
+        index = loadHelpIndex();
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Help index unavailable: ${String(e)}` }], isError: true };
+    }
+    const help = index[commandName];
+    if (!help) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: stalePrefix +
+                        `Command '${commandName}' not found in the help index.\n` +
+                        `Use list_dbatools_commands to discover available commands.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const paramLines = help.parameters.length === 0
+        ? "  (none documented)"
+        : help.parameters
+            .map((p) => {
+            const req = p.required ? " [REQUIRED]" : "";
+            const aliases = p.aliases.length > 0
+                ? `  aliases: ${p.aliases.join(", ")}`
+                : "";
+            const pipeline = p.pipelineInput ? "  pipeline input: yes" : "";
+            return (`  -${p.name} <${p.type}>${req}` +
+                `${aliases}${pipeline}\n    ${p.description || "(no description)"}`);
+        })
+            .join("\n\n");
+    const exampleLines = help.examples.length === 0
+        ? "  (none documented)"
+        : help.examples
+            .slice(0, 5)
+            .map((ex, i) => `--- Example ${i + 1}${ex.title ? ": " + ex.title : ""} ---\n` +
+            `${ex.code}\n` +
+            (ex.remarks ? `Remarks: ${ex.remarks}` : ""))
+            .join("\n\n");
+    const text = [
+        `NAME:        ${help.name}`,
+        `RISK LEVEL:  ${help.riskLevel}`,
+        `VERB / NOUN: ${help.verb} / ${help.noun}`,
+        ``,
+        `SYNOPSIS`,
+        `--------`,
+        help.synopsis || "(none)",
+        ``,
+        `DESCRIPTION`,
+        `-----------`,
+        help.description || "(none)",
+        ``,
+        `PARAMETERS`,
+        `----------`,
+        paramLines,
+        ``,
+        `EXAMPLES`,
+        `--------`,
+        exampleLines,
+        help.relatedLinks.length > 0
+            ? `\nRELATED LINKS\n-------------\n${help.relatedLinks.join("\n")}`
+            : "",
+    ]
+        .join("\n")
+        .trim();
+    return { content: [{ type: "text", text: stalePrefix + text }] };
+});
+// ---------------------------------------------------------------------------
+// Tool: invoke_dbatools_command
+// ---------------------------------------------------------------------------
+server.tool("invoke_dbatools_command", "Execute a dbatools command via PowerShell and return structured JSON output. Non-readonly commands require confirm:true when safe mode is enabled.", {
+    commandName: z
+        .string()
+        .max(100)
+        .describe("Exact dbatools command name to execute, e.g. Get-DbaDatabase"),
+    parameters: z
+        .record(z.unknown())
+        .default({})
+        .describe("Key-value map of parameters. Strings, numbers, and booleans map directly to PowerShell parameters. " +
+        "For SQL authentication pass SqlCredential as an object: { \"username\": \"sa\", \"password\": \"secret\" }. " +
+        "Example: { \"SqlInstance\": \"localhost,2022\", \"SqlCredential\": { \"username\": \"sa\", \"password\": \"P@ssw0rd\" } }"),
+    confirm: z
+        .boolean()
+        .default(false)
+        .describe("Set to true to allow execution of change/destructive commands (required when safeMode is on)"),
+}, async ({ commandName, parameters, confirm }) => {
+    let index;
+    try {
+        index = loadHelpIndex();
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `Help index unavailable: ${String(e)}` }], isError: true };
+    }
+    const help = index[commandName];
+    if (!help) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Unknown command: '${commandName}'.\n` +
+                        `Use list_dbatools_commands to discover available commands.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Safety gate: block non-readonly commands unless confirmed
+    if (config.safeMode && help.riskLevel !== "readonly" && !confirm) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Command '${commandName}' has risk level '${help.riskLevel}'.\n` +
+                        `Set confirm: true to allow execution, or use a readonly command instead.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    let script;
+    try {
+        script = buildPowerShellScript(commandName, parameters, config.maxOutputRows);
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `Parameter validation error: ${String(e)}` }],
+            isError: true,
+        };
+    }
+    let result;
+    try {
+        result = await runPowerShell(script, config);
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `PowerShell execution failed: ${String(e)}` }],
+            isError: true,
+        };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Command failed (exit ${result.exitCode}):\n` +
+                        (result.stderr || result.stdout || "(no output)"),
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Try to parse structured output
+    let parsed = undefined;
+    const trimmed = result.stdout.trim();
+    if (trimmed) {
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            // Not JSON — return raw text
+        }
+    }
+    const recordCount = Array.isArray(parsed)
+        ? parsed.length
+        : parsed != null
+            ? 1
+            : 0;
+    const summary = `Executed '${commandName}' — ${recordCount} record(s) returned.`;
+    const body = parsed
+        ? JSON.stringify(parsed, null, 2)
+        : trimmed || "(no output)";
+    const stderrSection = result.stderr.trim() ? `\n\nSTDERR:\n${result.stderr.trim()}` : "";
+    return {
+        content: [
+            { type: "text", text: `${summary}\n\n${body}${stderrSection}` },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Tool: check_dbatools_environment
+// ---------------------------------------------------------------------------
+server.tool("check_dbatools_environment", "Verify that PowerShell and the dbatools module are installed and report the help-index status.", {}, async () => {
+    const check = await checkDbatools(config);
+    if (!check.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `dbatools not available: ${check.error}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    let indexInfo = "Help index: not generated yet (run 'npm run refresh-help')";
+    let vsMismatch = "";
+    try {
+        const manifest = loadHelpManifest();
+        indexInfo =
+            `Help index: ${manifest.commandCount} commands indexed\n` +
+                `  dbatools version in index: ${manifest.dbatoolsVersion}\n` +
+                `  Generated at:              ${manifest.generatedAt}`;
+        const vs = await checkVersionMismatch(config, manifest.dbatoolsVersion);
+        // Invalidate cached state so next tool call re-evaluates
+        versionState = vs;
+        vsMismatch = vs.message;
+    }
+    catch {
+        // Index missing — that's fine, non-fatal
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: [
+                    `dbatools ${check.version} is installed and ready.`,
+                    indexInfo,
+                    vsMismatch,
+                    `Safe mode:       ${config.safeMode ? "ON (non-readonly commands require confirm:true)" : "OFF"}`,
+                    `Max output rows: ${config.maxOutputRows}`,
+                    `Timeout:         ${config.commandTimeout}s`,
+                ].filter(Boolean).join("\n"),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tool-registry.d.ts

@@ -0,0 +1,34 @@
+import type { DbatoolsCommandHelp } from "./types.js";
+/**
+ * Classify a dbatools command into a risk tier based on its verb.
+ * readonly  — safe to run without confirmation
+ * change    — modifies state but is reversible
+ * destructive — data loss risk; blocked by safe mode until confirm:true
+ */
+export declare function classifyCommand(name: string): "readonly" | "change" | "destructive";
+/**
+ * Credential descriptor accepted in the `parameters` map under the key `SqlCredential`.
+ * Pass as: { "SqlCredential": { "username": "sa", "password": "secret" } }
+ */
+export interface SqlCredentialDescriptor {
+    username: string;
+    password: string;
+}
+/**
+ * Build a self-contained PowerShell script that imports dbatools, invokes the
+ * requested command with the supplied parameters, and emits JSON via
+ * ConvertTo-Json so the MCP server gets structured output.
+ *
+ * String values are single-quoted and internal single-quotes are escaped.
+ * Switch parameters are passed as bare flags when value is true.
+ *
+ * Special parameter: SqlCredential — accepts { username, password } and is
+ * converted into a PSCredential object so SQL authentication works.
+ */
+export declare function buildPowerShellScript(commandName: string, args: Record<string, unknown>, maxRows: number): string;
+/**
+ * Format a DbatoolsCommandHelp record into a concise MCP tool description
+ * (≤ 1024 chars, which is the MCP spec recommendation).
+ */
+export declare function buildToolDescription(cmd: DbatoolsCommandHelp): string;
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAWtD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GACX,UAAU,GAAG,QAAQ,GAAG,aAAa,CAKvC;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAWD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,MAAM,GACd,MAAM,CAuDR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAQrE"}

package/dist/tool-registry.js

@@ -0,0 +1,102 @@
+const READONLY_VERBS = new Set([
+    "Get", "Test", "Find", "Measure", "Select", "Show",
+    "Watch", "Compare", "Search", "Resolve",
+]);
+const DESTRUCTIVE_VERBS = new Set([
+    "Remove", "Drop", "Delete", "Uninstall", "Revoke", "Disable", "Reset",
+]);
+/**
+ * Classify a dbatools command into a risk tier based on its verb.
+ * readonly  — safe to run without confirmation
+ * change    — modifies state but is reversible
+ * destructive — data loss risk; blocked by safe mode until confirm:true
+ */
+export function classifyCommand(name) {
+    const verb = name.split("-")[0] ?? "";
+    if (READONLY_VERBS.has(verb))
+        return "readonly";
+    if (DESTRUCTIVE_VERBS.has(verb))
+        return "destructive";
+    return "change";
+}
+function isSqlCredentialDescriptor(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v["username"] === "string" &&
+        typeof v["password"] === "string");
+}
+/**
+ * Build a self-contained PowerShell script that imports dbatools, invokes the
+ * requested command with the supplied parameters, and emits JSON via
+ * ConvertTo-Json so the MCP server gets structured output.
+ *
+ * String values are single-quoted and internal single-quotes are escaped.
+ * Switch parameters are passed as bare flags when value is true.
+ *
+ * Special parameter: SqlCredential — accepts { username, password } and is
+ * converted into a PSCredential object so SQL authentication works.
+ */
+export function buildPowerShellScript(commandName, args, maxRows) {
+    // Validate command name against an allowlist pattern (letters, digits, hyphens only)
+    if (!/^[A-Za-z]+-[A-Za-z][A-Za-z0-9]*$/.test(commandName)) {
+        throw new Error(`Invalid command name: ${commandName}`);
+    }
+    const preambleLines = [];
+    const splatEntries = [];
+    for (const [key, value] of Object.entries(args)) {
+        // Validate parameter key (letters, digits only)
+        if (!/^[A-Za-z][A-Za-z0-9]*$/.test(key)) {
+            throw new Error(`Invalid parameter name: ${key}`);
+        }
+        if (value === null || value === undefined)
+            continue;
+        // Special case: SqlCredential object → build a PSCredential in the script
+        if (key === "SqlCredential" && isSqlCredentialDescriptor(value)) {
+            const escapedUser = value.username.replace(/'/g, "''");
+            const escapedPass = value.password.replace(/'/g, "''");
+            preambleLines.push(`$__securePass = ConvertTo-SecureString '${escapedPass}' -AsPlainText -Force`, `$__cred = New-Object System.Management.Automation.PSCredential('${escapedUser}', $__securePass)`);
+            splatEntries.push(`    SqlCredential = $__cred`);
+            continue;
+        }
+        if (typeof value === "boolean") {
+            if (value)
+                splatEntries.push(`    ${key} = $true`);
+        }
+        else if (typeof value === "number") {
+            if (!Number.isFinite(value))
+                throw new Error(`Non-finite number for -${key}`);
+            splatEntries.push(`    ${key} = ${value}`);
+        }
+        else {
+            // Sanitize string: escape embedded single-quotes
+            const escaped = String(value).replace(/'/g, "''");
+            splatEntries.push(`    ${key} = '${escaped}'`);
+        }
+    }
+    const splatBlock = splatEntries.length > 0
+        ? [`$params = @{`, ...splatEntries, `}`].join("\n")
+        : `$params = @{}`;
+    return [
+        `Set-StrictMode -Off`,
+        `$ErrorActionPreference = 'Stop'`,
+        `Import-Module dbatools -ErrorAction Stop`,
+        ...preambleLines,
+        splatBlock,
+        `$result = ${commandName} @params | Select-Object -First ${maxRows}`,
+        `if ($null -eq $result) { Write-Output '[]'; exit 0 }`,
+        `$result | ConvertTo-Json -Depth 5 -Compress`,
+    ].join("\n");
+}
+/**
+ * Format a DbatoolsCommandHelp record into a concise MCP tool description
+ * (≤ 1024 chars, which is the MCP spec recommendation).
+ */
+export function buildToolDescription(cmd) {
+    const base = cmd.synopsis || cmd.description || cmd.name;
+    const risk = cmd.riskLevel === "readonly"
+        ? ""
+        : ` [${cmd.riskLevel.toUpperCase()} — requires confirm:true]`;
+    const full = `${base}${risk}`;
+    return full.length > 1024 ? full.substring(0, 1021) + "..." : full;
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/tool-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+/** Represents one parameter from Get-Help -Full output */
+export interface DbatoolsParameter {
+    name: string;
+    type: string;
+    required: boolean;
+    aliases: string[];
+    pipelineInput: boolean;
+    description: string;
+    defaultValue?: string;
+}
+/** One example block from Get-Help -Full output */
+export interface DbatoolsExample {
+    title: string;
+    code: string;
+    remarks: string;
+}
+/** Full normalized help payload for one dbatools command */
+export interface DbatoolsCommandHelp {
+    name: string;
+    verb: string;
+    noun: string;
+    synopsis: string;
+    description: string;
+    parameters: DbatoolsParameter[];
+    examples: DbatoolsExample[];
+    relatedLinks: string[];
+    tags: string[];
+    riskLevel: "readonly" | "change" | "destructive";
+}
+/** The full dbatools-help.json manifest written by refresh-help.ps1 */
+export interface HelpManifest {
+    generatedAt: string;
+    dbatoolsVersion: string;
+    commandCount: number;
+    commands: HelpIndex;
+}
+/** Keyed by command name, e.g. "Get-DbaDatabase" */
+export type HelpIndex = Record<string, DbatoolsCommandHelp>;
+/** Result returned from running a PowerShell script */
+export interface PowerShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Runtime configuration resolved from environment variables */
+export interface ServerConfig {
+    powershellExe: string;
+    /** When true, non-readonly commands require confirm:true */
+    safeMode: boolean;
+    /** Maximum rows piped through Select-Object before ConvertTo-Json */
+    maxOutputRows: number;
+    /** Seconds before the PowerShell child process is killed */
+    commandTimeout: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,SAAS,EAAE,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;CAClD;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,oDAAoD;AACpD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE5D,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/generated/.gitkeep

@@ -0,0 +1,3 @@
+# This directory is created by scripts/refresh-help.ps1
+# dbatools-help.json is generated locally and is intentionally gitignored.
+# Run: npm run refresh-help

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "dbatools-mcp-server",
+  "mcpName": "io.github.dataplat/dbatools-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for the dbatools PowerShell module — exposes dbatools commands as MCP tools driven by comment-based help",
+  "keywords": [
+    "dbatools",
+    "mcp",
+    "sql server",
+    "powershell",
+    "database"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dataplat/dbatools-mcp-server.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "generated/.gitkeep",
+    "scripts/refresh-help.ps1"
+  ],
+  "bin": {
+    "dbatools-mcp-server": "./dist/server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/server.ts",
+    "start": "node dist/server.js",
+    "refresh-help": "pwsh -NonInteractive -File scripts/refresh-help.ps1",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --passWithNoTests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^22.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "jest": {
+    "preset": "ts-jest/presets/default-esm",
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "useESM": true
+        }
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/scripts/refresh-help.ps1

@@ -0,0 +1,192 @@
+<#
+.SYNOPSIS
+    Generates generated/dbatools-help.json by extracting comment-based help from
+    every command in the locally installed dbatools module.
+
+.DESCRIPTION
+    Run this script whenever dbatools is installed or updated.
+    Output is consumed by the MCP server at startup and cached for the session.
+
+    Usage: npm run refresh-help
+           pwsh -File scripts/refresh-help.ps1
+
+.PARAMETER OutputPath
+    Override the output file path (default: <repo-root>/generated/dbatools-help.json)
+
+.PARAMETER MaxCommands
+    Limit to N commands for quick development iterations (0 = all commands)
+#>
+[CmdletBinding()]
+param(
+    [string]$OutputPath = "",
+    [int]$MaxCommands = 0
+)
+
+$ErrorActionPreference = 'Stop'
+$InformationPreference = 'Continue'
+
+# ---------------------------------------------------------------------------
+# Resolve paths
+# ---------------------------------------------------------------------------
+$ScriptDir   = Split-Path -Parent $PSCommandPath
+$RepoRoot    = Split-Path -Parent $ScriptDir
+$OutputDir   = Join-Path $RepoRoot 'generated'
+$DefaultOut  = Join-Path $OutputDir 'dbatools-help.json'
+
+if ($OutputPath -eq "") { $OutputPath = $DefaultOut }
+
+if (-not (Test-Path $OutputDir)) {
+    New-Item -ItemType Directory -Path $OutputDir | Out-Null
+    Write-Information "Created directory: $OutputDir"
+}
+
+# ---------------------------------------------------------------------------
+# Verify dbatools
+# ---------------------------------------------------------------------------
+$module = Get-Module -ListAvailable -Name dbatools |
+          Sort-Object Version -Descending |
+          Select-Object -First 1
+
+if (-not $module) {
+    Write-Error "dbatools is not installed.`nRun: Install-Module dbatools -Scope CurrentUser"
+    exit 1
+}
+
+Write-Information "Found dbatools $($module.Version) at $($module.ModuleBase)"
+Write-Information "Importing module..."
+Import-Module dbatools -ErrorAction Stop
+
+# ---------------------------------------------------------------------------
+# Enumerate commands
+# ---------------------------------------------------------------------------
+$commands = Get-Command -Module dbatools | Sort-Object Name
+
+if ($MaxCommands -gt 0) {
+    $commands = $commands | Select-Object -First $MaxCommands
+    Write-Warning "MaxCommands=$MaxCommands — indexing a subset only."
+}
+
+$total = $commands.Count
+Write-Information "Indexing $total commands..."
+
+# ---------------------------------------------------------------------------
+# Risk classification helpers
+# ---------------------------------------------------------------------------
+$ReadonlyVerbs    = @('Get','Test','Find','Measure','Select','Show','Watch','Compare','Search','Resolve')
+$DestructiveVerbs = @('Remove','Drop','Delete','Uninstall','Revoke','Disable','Reset')
+
+function Get-RiskLevel([string]$verb) {
+    if ($ReadonlyVerbs    -contains $verb) { return 'readonly' }
+    if ($DestructiveVerbs -contains $verb) { return 'destructive' }
+    return 'change'
+}
+
+# ---------------------------------------------------------------------------
+# Help extraction loop
+# ---------------------------------------------------------------------------
+$index     = [System.Collections.Specialized.OrderedDictionary]::new()
+$failures  = 0
+$counter   = 0
+
+foreach ($cmd in $commands) {
+    $counter++
+    if ($counter % 100 -eq 0) {
+        Write-Information "  $counter / $total  ($([Math]::Round($counter/$total*100))%)"
+    }
+
+    try {
+        $help = Get-Help $cmd.Name -Full -ErrorAction SilentlyContinue
+
+        # --- Parameters ---------------------------------------------------
+        $params = [System.Collections.Generic.List[hashtable]]::new()
+        if ($help.parameters -and $help.parameters.parameter) {
+            foreach ($p in $help.parameters.parameter) {
+                $desc = if ($p.description) {
+                    ($p.description | ForEach-Object { $_.Text }) -join ' '
+                } else { '' }
+
+                $aliasArr = if ($p.aliases -and $p.aliases -ne 'None') {
+                    @($p.aliases -split ',\s*' | Where-Object { $_ -ne '' })
+                } else { @() }
+
+                $params.Add([ordered]@{
+                    name          = [string]$p.name
+                    type          = if ($p.type -and $p.type.name) { [string]$p.type.name } else { 'Object' }
+                    required      = ($p.required -eq 'true')
+                    aliases       = $aliasArr
+                    pipelineInput = ($p.pipelineInput -and $p.pipelineInput -ne 'false')
+                    description   = $desc.Trim()
+                    defaultValue  = if ($p.defaultValue) { [string]$p.defaultValue } else { $null }
+                })
+            }
+        }
+
+        # --- Examples -----------------------------------------------------
+        $examples = [System.Collections.Generic.List[hashtable]]::new()
+        if ($help.examples -and $help.examples.example) {
+            foreach ($ex in $help.examples.example) {
+                $remarks = if ($ex.remarks) {
+                    ($ex.remarks | ForEach-Object { $_.Text }) -join ' '
+                } else { '' }
+
+                $examples.Add([ordered]@{
+                    title   = ([string]($ex.title ?? '')).TrimStart('-').Trim()
+                    code    = ([string]($ex.code ?? '')).Trim()
+                    remarks = $remarks.Trim()
+                })
+            }
+        }
+
+        # --- Related links ------------------------------------------------
+        $links = @()
+        if ($help.relatedLinks -and $help.relatedLinks.navigationLink) {
+            $links = @(
+                $help.relatedLinks.navigationLink |
+                ForEach-Object { if ($_.uri) { $_.uri } elseif ($_.linkText) { $_.linkText } } |
+                Where-Object { $_ -and $_ -ne '' }
+            )
+        }
+
+        # --- Synopsis / Description ---------------------------------------
+        $synopsis = if ($help.Synopsis) { $help.Synopsis.Trim() } else { '' }
+
+        $description = if ($help.description) {
+            ($help.description | ForEach-Object { $_.Text }) -join ' '
+        } else { '' }
+
+        $index[$cmd.Name] = [ordered]@{
+            name         = $cmd.Name
+            verb         = $cmd.Verb
+            noun         = $cmd.Noun
+            synopsis     = $synopsis
+            description  = $description.Trim()
+            parameters   = $params.ToArray()
+            examples     = $examples.ToArray()
+            relatedLinks = $links
+            tags         = @()
+            riskLevel    = Get-RiskLevel $cmd.Verb
+        }
+    }
+    catch {
+        $failures++
+        Write-Warning "[$counter/$total] Failed to get help for $($cmd.Name): $_"
+    }
+}
+
+# ---------------------------------------------------------------------------
+# Write manifest
+# ---------------------------------------------------------------------------
+$manifest = [ordered]@{
+    generatedAt      = (Get-Date -Format 'o')
+    dbatoolsVersion  = $module.Version.ToString()
+    commandCount     = $index.Count
+    commands         = $index
+}
+
+$manifest | ConvertTo-Json -Depth 12 | Set-Content -Path $OutputPath -Encoding UTF8
+
+Write-Information ""
+Write-Information "Done! Indexed $($index.Count) commands -> $OutputPath"
+if ($failures -gt 0) {
+    Write-Warning "$failures command(s) failed to index (see warnings above)."
+}