Skip to content

Commit 0bac0d0

Browse files
ClaudioESSilvaClaudioESSilva
committed
Initial commit
0 parents  commit 0bac0d0

File tree

14 files changed

+6662
-0
lines changed

14 files changed

+6662
-0
lines changed

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
node_modules/
2+
dist/
3+
generated/dbatools-help.json
4+
*.js.map
5+
.env
6+
.env.local
7+
*.log

‎.vscode/mcp.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"servers": {
3+
"dbatools": {
4+
"type": "stdio",
5+
"command": "node",
6+
"args": ["${workspaceFolder}/dist/server.js"],
7+
"env": {
8+
"DBATOOLS_SAFE_MODE": "true",
9+
"MAX_OUTPUT_ROWS": "100",
10+
"COMMAND_TIMEOUT_SECONDS": "60"
11+
}
12+
}
13+
}
14+
}

‎LICENSE‎

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

‎README.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# dbatools-mcp-server
2+
3+
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the [dbatools](https://dbatools.io) PowerShell module.
4+
5+
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**.
6+
7+
---
8+
9+
## Features
10+
11+
- **`list_dbatools_commands`** — search commands by verb, noun, keyword, or risk level
12+
- **`get_dbatools_command_help`** — full normalized help (synopsis, parameters, examples) from `Get-Help -Full`
13+
- **`invoke_dbatools_command`** — execute any dbatools command with safe parameter validation, risk gating, and structured JSON output
14+
- **`check_dbatools_environment`** — verify PowerShell + dbatools installation, index freshness, and version alignment
15+
- **Version mismatch detection** — warns when installed dbatools version differs from the indexed version
16+
- **Safe mode** — non-readonly commands require explicit `confirm: true` to execute
17+
- **SQL Authentication support** — pass `SqlCredential: { username, password }` for SQL auth instances
18+
19+
---
20+
21+
## Prerequisites
22+
23+
- [Node.js](https://nodejs.org/) 20+
24+
- [PowerShell 7+](https://github.com/PowerShell/PowerShell/releases) (`pwsh`)
25+
- [dbatools](https://dbatools.io/download) PowerShell module
26+
27+
```powershell
28+
Install-Module dbatools -Scope CurrentUser
29+
```
30+
31+
---
32+
33+
## Quick Start
34+
35+
```powershell
36+
# 1. Clone the repo
37+
git clone https://github.com/Dataplat/dbatools-mcp-server.git
38+
cd dbatools-mcp-server
39+
40+
# 2. Install Node dependencies
41+
npm install
42+
43+
# 3. Generate the help index from your local dbatools installation
44+
npm run refresh-help
45+
46+
# 4. Build
47+
npm run build
48+
```
49+
50+
Then open the folder in VS Code — the `.vscode/mcp.json` file automatically registers the MCP server.
51+
52+
---
53+
54+
## Connecting to VS Code
55+
56+
The included [`.vscode/mcp.json`](.vscode/mcp.json) registers the server as a local STDIO MCP server.
57+
Open this folder in VS Code and the server will appear in the GitHub Copilot MCP panel.
58+
59+
```json
60+
{
61+
"servers": {
62+
"dbatools": {
63+
"type": "stdio",
64+
"command": "node",
65+
"args": ["${workspaceFolder}/dist/server.js"],
66+
"env": {
67+
"DBATOOLS_SAFE_MODE": "true",
68+
"MAX_OUTPUT_ROWS": "100",
69+
"COMMAND_TIMEOUT_SECONDS": "60"
70+
}
71+
}
72+
}
73+
}
74+
```
75+
76+
---
77+
78+
## Configuration
79+
80+
All settings are controlled via environment variables (set in `.vscode/mcp.json` or your shell):
81+
82+
| Variable | Default | Description |
83+
|---|---|---|
84+
| `PWSH_EXE` | `pwsh` | Path to PowerShell executable |
85+
| `DBATOOLS_SAFE_MODE` | `true` | When `true`, non-readonly commands require `confirm: true` |
86+
| `MAX_OUTPUT_ROWS` | `100` | Maximum rows returned per command execution |
87+
| `COMMAND_TIMEOUT_SECONDS` | `60` | Seconds before PowerShell process is killed |
88+
89+
---
90+
91+
## Refreshing the Help Index
92+
93+
The help index (`generated/dbatools-help.json`) is generated from your locally installed dbatools module.
94+
Re-run whenever dbatools is updated:
95+
96+
```powershell
97+
Update-Module dbatools -Scope CurrentUser
98+
npm run refresh-help
99+
```
100+
101+
The server detects version mismatches at runtime and warns you when the index is stale.
102+
103+
---
104+
105+
## Risk Levels
106+
107+
Commands are automatically classified by verb:
108+
109+
| Risk Level | Verbs | Behavior |
110+
|---|---|---|
111+
| `readonly` | Get, Test, Find, Compare, … | Always allowed |
112+
| `change` | Set, New, Add, Copy, Enable, … | Requires `confirm: true` in safe mode |
113+
| `destructive` | Remove, Drop, Disable, Reset, … | Requires `confirm: true` in safe mode |
114+
115+
---
116+
117+
## SQL Authentication
118+
119+
For SQL-auth-only instances (e.g. Docker), pass credentials via the `SqlCredential` parameter:
120+
121+
```json
122+
{
123+
"SqlInstance": "localhost,1433",
124+
"SqlCredential": { "username": "<SqlLogin>", "password": "YourPassword" }
125+
}
126+
```
127+
128+
---
129+
130+
## Project Structure
131+
132+
```
133+
dbatools-mcp-server/
134+
├── src/
135+
│ ├── server.ts # MCP server entry point, tool definitions
136+
│ ├── powershell.ts # PowerShell process runner, health checks, version detection
137+
│ ├── help-indexer.ts # Help manifest loader and command search
138+
│ ├── tool-registry.ts # Risk classification, safe argument builder
139+
│ └── types.ts # Shared TypeScript interfaces
140+
├── scripts/
141+
│ └── refresh-help.ps1 # Generates generated/dbatools-help.json
142+
├── generated/ # Help index (gitignored, generated locally)
143+
├── .vscode/
144+
│ └── mcp.json # VS Code MCP local server registration
145+
└── dist/ # Compiled output (gitignored)
146+
```
147+
148+
---
149+
150+
## Contributing
151+
152+
Contributions are welcome! Please open an issue first for significant changes.
153+
154+
This project follows the same community spirit as [dbatools](https://github.com/dataplat/dbatools).
155+
156+
---
157+
158+
## License
159+
160+
[MIT](LICENSE) — © 2026 DataPlat contributors

‎generated/.gitkeep‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# This directory is created by scripts/refresh-help.ps1
2+
# dbatools-help.json is generated locally and is intentionally gitignored.
3+
# Run: npm run refresh-help

0 commit comments

Comments
 (0)