mcpad 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mcpad-0.1.0/PKG-INFO +251 -0
- mcpad-0.1.0/README.md +225 -0
- mcpad-0.1.0/pyproject.toml +77 -0
- mcpad-0.1.0/pyproject.toml.orig +91 -0
- mcpad-0.1.0/src/mcpad/__init__.py +21 -0
- mcpad-0.1.0/src/mcpad/server.py +397 -0
mcpad-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcpad
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A FastMCP server exposing the msad Active Directory / LDAP library
|
|
5
|
+
Keywords: active-directory,ldap,mcp,kerberos,ad
|
|
6
|
+
Author: Matteo Redaelli
|
|
7
|
+
Author-email: Matteo Redaelli <matteo.redaelli@gmail.com>
|
|
8
|
+
License-Expression: GPL-3.0-or-later
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: System Administrators
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory :: LDAP
|
|
19
|
+
Requires-Dist: fastmcp>=4.0.9
|
|
20
|
+
Requires-Dist: msad>=0.6.0
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Project-URL: Homepage, https://github.com/matteoredaelli/mcpAD
|
|
23
|
+
Project-URL: Repository, https://github.com/matteoredaelli/mcpAD
|
|
24
|
+
Project-URL: Issues, https://github.com/matteoredaelli/mcpAD/issues
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# mcpAD
|
|
28
|
+
|
|
29
|
+
A [FastMCP](https://gofastmcp.com) server that exposes the
|
|
30
|
+
[`msad`](https://github.com/matteoredaelli/msad) Active Directory / LDAP library as MCP tools.
|
|
31
|
+
|
|
32
|
+
Built with **Python 3.14** and **uv**. It reuses the typed, public `msad` API
|
|
33
|
+
(search users/groups, memberships, account status). All tools are read-only.
|
|
34
|
+
|
|
35
|
+
## Tools
|
|
36
|
+
|
|
37
|
+
| Tool | Description |
|
|
38
|
+
|---|---|
|
|
39
|
+
| `find_users` | Find users by name/surname/mail/sam/department (ANDed, `*` wildcards) |
|
|
40
|
+
| `get_user` | Get a single user (exact match) |
|
|
41
|
+
| `find_groups` | Find groups (`*` wildcards) |
|
|
42
|
+
| `get_group` | Get a single group (exact match) |
|
|
43
|
+
| `find_computers` | Find computers by name/dns/os (`*` wildcards) |
|
|
44
|
+
| `get_computer` | Get a single computer (sAMAccountName/cn/dNSHostName) |
|
|
45
|
+
| `find_ous` | Find organizational units by name (`*` wildcards) |
|
|
46
|
+
| `get_ou` | Get a single OU by its `ou` name or full DN (exact match) |
|
|
47
|
+
| `get_ou_contents` | List objects under an OU (optionally filtered by `object_class`) |
|
|
48
|
+
| `find_inactive_users` | Find users whose last logon is older than `days` (default 90) |
|
|
49
|
+
| `find_stale_computers` | Find computers whose last logon is older than `days` (default 90) |
|
|
50
|
+
| `get_domain_info` | Domain object: security-relevant settings and metadata (audit) |
|
|
51
|
+
| `get_password_policy` | Default domain password policy (audit) |
|
|
52
|
+
| `get_password_policy_violations` | Users whose password violates the policy (audit) |
|
|
53
|
+
| `get_privileged_groups` | Well-known privileged groups with member counts (audit) |
|
|
54
|
+
| `get_by_dn` | Fetch any entry directly by its DN (resolve `manager` / `managedBy`) |
|
|
55
|
+
| `group_members` | List group members (direct or `nested`) |
|
|
56
|
+
| `user_groups` | List a user's groups (nested by default) |
|
|
57
|
+
| `is_member` | Is a user a (nested) member of a group? |
|
|
58
|
+
| `is_disabled` | Is an account disabled? |
|
|
59
|
+
| `is_locked` | Is an account locked? |
|
|
60
|
+
| `test_connection` | Test AD connectivity and bind (returns ok/target/auth/error) |
|
|
61
|
+
| `health` | Server health check (server name, msad version, connectivity) |
|
|
62
|
+
|
|
63
|
+
The `find_users`, `find_groups`, `find_computers` and `find_ous` tools accept an
|
|
64
|
+
optional `base` (a DN, e.g. an OU) to restrict the search to that subtree
|
|
65
|
+
instead of the whole domain.
|
|
66
|
+
|
|
67
|
+
### Returned attributes
|
|
68
|
+
|
|
69
|
+
By default `get_user` / `find_users` return a useful attribute set: identity
|
|
70
|
+
fields plus `manager` — the **distinguished name (DN)** of the user's manager,
|
|
71
|
+
e.g. `CN=Anna Bianchi,OU=Staff,DC=group,DC=example,DC=com` — as well as
|
|
72
|
+
`memberOf` (direct group DNs), `userAccountControl`, `accountExpires`,
|
|
73
|
+
`lastLogonTimestamp` and `whenCreated`. Group lookups include `managedBy` (the
|
|
74
|
+
DN of the group's owner), `member`, `groupType` and `whenCreated`.
|
|
75
|
+
|
|
76
|
+
To expand a manager (or any DN-valued field) into a full record, call
|
|
77
|
+
`get_by_dn` with that DN. This is a direct, efficient lookup (the DN is used as
|
|
78
|
+
the search base), so an agent can do: `get_user("mrossi")` → read `manager` →
|
|
79
|
+
`get_by_dn("<that DN>")`.
|
|
80
|
+
|
|
81
|
+
## Authentication & connection
|
|
82
|
+
|
|
83
|
+
The server has **no connection settings of its own**: it reuses the `msad`
|
|
84
|
+
configuration file, `~/.msad.toml` by default (create it with `msad init`).
|
|
85
|
+
Each tool call opens a short-lived connection through `msad.connect()`.
|
|
86
|
+
|
|
87
|
+
### Domain parameters (`~/.msad.toml`)
|
|
88
|
+
|
|
89
|
+
```toml
|
|
90
|
+
[defaults]
|
|
91
|
+
domain = "group" # used when a tool call omits `domain`
|
|
92
|
+
|
|
93
|
+
[domains.group]
|
|
94
|
+
host = "dc.example.com" # hostname only (no scheme, no :port)
|
|
95
|
+
base = "dc=group,dc=example,dc=com"
|
|
96
|
+
port = 636 # default: 389
|
|
97
|
+
use_ssl = true # default: false (true = LDAPS)
|
|
98
|
+
# user = "svc_account" # optional (see auth below)
|
|
99
|
+
# password = "..." # optional
|
|
100
|
+
|
|
101
|
+
# A second domain (here using user/password auth):
|
|
102
|
+
[domains.lab]
|
|
103
|
+
host = "dc.lab.example.com"
|
|
104
|
+
base = "dc=lab,dc=example,dc=com"
|
|
105
|
+
port = 636
|
|
106
|
+
use_ssl = true
|
|
107
|
+
user = "svc_reader"
|
|
108
|
+
password = "s3cr3t"
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
You can declare several `[domains.<name>]` blocks and pick one per call with the
|
|
112
|
+
tool's `domain` argument, or globally via `MSAD_DOMAIN`. For example, an agent
|
|
113
|
+
can call `find_users(surname="Rossi", domain="lab")` to target the `lab` domain
|
|
114
|
+
while `[defaults].domain` stays `group`.
|
|
115
|
+
|
|
116
|
+
### Overrides via environment
|
|
117
|
+
|
|
118
|
+
- `MSAD_DOMAIN` — default domain when a tool call omits `domain`
|
|
119
|
+
- `MSAD_CONFIG_FILE` — path to an alternative TOML config
|
|
120
|
+
|
|
121
|
+
### Authentication modes
|
|
122
|
+
|
|
123
|
+
The mode is chosen **automatically** from the domain block:
|
|
124
|
+
|
|
125
|
+
- **Kerberos (SASL)** — when `user`/`password` are *not both* set (the default).
|
|
126
|
+
Obtain a ticket first:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
kinit # or: kinit <user>@REALM
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The server relies on the system Kerberos ticket cache (or a keytab via
|
|
133
|
+
`KRB5_CLIENT_KTNAME`). If the ticket is missing or expired, tools fail with a
|
|
134
|
+
clean `MsadConnectionError` message. When running as a background/remote
|
|
135
|
+
service, make sure that process can see a valid ticket or keytab.
|
|
136
|
+
|
|
137
|
+
- **User / password** — when **both** `user` and `password` are set. Simple LDAP
|
|
138
|
+
bind. The password is stored in clear text in the TOML, so restrict the file
|
|
139
|
+
permissions (`chmod 600 ~/.msad.toml`).
|
|
140
|
+
|
|
141
|
+
> Note: setting only one of `user`/`password` silently falls back to Kerberos.
|
|
142
|
+
> Set both, or neither.
|
|
143
|
+
|
|
144
|
+
Use LDAPS (`port = 636`, `use_ssl = true`) whenever possible.
|
|
145
|
+
|
|
146
|
+
## Running
|
|
147
|
+
|
|
148
|
+
Using uvx:
|
|
149
|
+
|
|
150
|
+
uvx --from git+https://github.com/matteoredaelli/mcpAD mcpAD
|
|
151
|
+
|
|
152
|
+
The `Makefile` wraps the common cases. Transport, host and port are
|
|
153
|
+
configurable:
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
make start-stdio # stdio (for local MCP clients)
|
|
157
|
+
make start-http # streamable-http on 127.0.0.1:8000
|
|
158
|
+
make start-http HOST=0.0.0.0 PORT=9000 # bind elsewhere
|
|
159
|
+
make start-sse # sse transport
|
|
160
|
+
make start TRANSPORT=streamable-http PORT=9000 # generic form
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Equivalent raw commands (the server reads `MCP_TRANSPORT` / `MCP_HOST` /
|
|
164
|
+
`MCP_PORT` from the environment):
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
uv run mcpad # stdio (default)
|
|
168
|
+
MCP_TRANSPORT=streamable-http MCP_PORT=9000 uv run mcpad
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
## Registering the server with an MCP client / agent
|
|
173
|
+
|
|
174
|
+
MCP clients (Claude Desktop, IDE agents, custom agents, ...) usually accept a
|
|
175
|
+
JSON config with a `mcpServers` map. Two deployment styles:
|
|
176
|
+
|
|
177
|
+
### Local (stdio) — the client launches the server
|
|
178
|
+
|
|
179
|
+
The client spawns the process and talks to it over stdio. This is the simplest
|
|
180
|
+
setup and keeps everything on your machine (including your Kerberos ticket).
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{
|
|
184
|
+
"mcpServers": {
|
|
185
|
+
"mcpAD": {
|
|
186
|
+
"command": "uv",
|
|
187
|
+
"args": [
|
|
188
|
+
"run",
|
|
189
|
+
"--directory", "/path/to/mcpAD",
|
|
190
|
+
"mcpad"
|
|
191
|
+
],
|
|
192
|
+
"env": {
|
|
193
|
+
"MSAD_DOMAIN": "group"
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Notes:
|
|
201
|
+
- `--directory` makes `uv` use this project's environment regardless of the
|
|
202
|
+
client's working directory.
|
|
203
|
+
- Kerberos: the spawned process inherits your environment, so a ticket obtained
|
|
204
|
+
with `kinit` in the same user session is used automatically. For an unattended
|
|
205
|
+
client, point it at a keytab (e.g. add `"KRB5_CLIENT_KTNAME": "/path/to.keytab"`
|
|
206
|
+
to `env`).
|
|
207
|
+
|
|
208
|
+
### Remote (streamable-http) — the server runs as a service
|
|
209
|
+
|
|
210
|
+
Start the server as a long-running HTTP service, then point the client at its
|
|
211
|
+
URL. Useful when the server runs on a host that has AD/Kerberos access while the
|
|
212
|
+
client runs elsewhere.
|
|
213
|
+
|
|
214
|
+
Start the service:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
make start-http HOST=0.0.0.0 PORT=9000
|
|
218
|
+
# serves the MCP endpoint at http://<host>:9000/mcp
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Client config referencing the URL:
|
|
222
|
+
|
|
223
|
+
```json
|
|
224
|
+
{
|
|
225
|
+
"mcpServers": {
|
|
226
|
+
"mcpAD": {
|
|
227
|
+
"transport": "http",
|
|
228
|
+
"url": "http://mcp-host.example.com:9000/mcp"
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Notes:
|
|
235
|
+
- The default streamable-http path is `/mcp`.
|
|
236
|
+
- The server itself performs no client authentication; if you expose it beyond
|
|
237
|
+
localhost, put it behind a reverse proxy / network controls and treat the AD
|
|
238
|
+
credentials on that host accordingly.
|
|
239
|
+
- Kerberos runs where the **server** runs: that host needs a valid ticket or a
|
|
240
|
+
keytab, not the client.
|
|
241
|
+
|
|
242
|
+
## Development
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
uv sync
|
|
246
|
+
uv run python -c "import asyncio; from mcpad import mcp; print(asyncio.run(mcp.list_tools()))"
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
The [`msad`](https://github.com/matteoredaelli/msad) dependency can be installed
|
|
250
|
+
from its Git repository, or as an editable local path during development so that
|
|
251
|
+
library changes are picked up immediately.
|
mcpad-0.1.0/README.md
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
# mcpAD
|
|
2
|
+
|
|
3
|
+
A [FastMCP](https://gofastmcp.com) server that exposes the
|
|
4
|
+
[`msad`](https://github.com/matteoredaelli/msad) Active Directory / LDAP library as MCP tools.
|
|
5
|
+
|
|
6
|
+
Built with **Python 3.14** and **uv**. It reuses the typed, public `msad` API
|
|
7
|
+
(search users/groups, memberships, account status). All tools are read-only.
|
|
8
|
+
|
|
9
|
+
## Tools
|
|
10
|
+
|
|
11
|
+
| Tool | Description |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `find_users` | Find users by name/surname/mail/sam/department (ANDed, `*` wildcards) |
|
|
14
|
+
| `get_user` | Get a single user (exact match) |
|
|
15
|
+
| `find_groups` | Find groups (`*` wildcards) |
|
|
16
|
+
| `get_group` | Get a single group (exact match) |
|
|
17
|
+
| `find_computers` | Find computers by name/dns/os (`*` wildcards) |
|
|
18
|
+
| `get_computer` | Get a single computer (sAMAccountName/cn/dNSHostName) |
|
|
19
|
+
| `find_ous` | Find organizational units by name (`*` wildcards) |
|
|
20
|
+
| `get_ou` | Get a single OU by its `ou` name or full DN (exact match) |
|
|
21
|
+
| `get_ou_contents` | List objects under an OU (optionally filtered by `object_class`) |
|
|
22
|
+
| `find_inactive_users` | Find users whose last logon is older than `days` (default 90) |
|
|
23
|
+
| `find_stale_computers` | Find computers whose last logon is older than `days` (default 90) |
|
|
24
|
+
| `get_domain_info` | Domain object: security-relevant settings and metadata (audit) |
|
|
25
|
+
| `get_password_policy` | Default domain password policy (audit) |
|
|
26
|
+
| `get_password_policy_violations` | Users whose password violates the policy (audit) |
|
|
27
|
+
| `get_privileged_groups` | Well-known privileged groups with member counts (audit) |
|
|
28
|
+
| `get_by_dn` | Fetch any entry directly by its DN (resolve `manager` / `managedBy`) |
|
|
29
|
+
| `group_members` | List group members (direct or `nested`) |
|
|
30
|
+
| `user_groups` | List a user's groups (nested by default) |
|
|
31
|
+
| `is_member` | Is a user a (nested) member of a group? |
|
|
32
|
+
| `is_disabled` | Is an account disabled? |
|
|
33
|
+
| `is_locked` | Is an account locked? |
|
|
34
|
+
| `test_connection` | Test AD connectivity and bind (returns ok/target/auth/error) |
|
|
35
|
+
| `health` | Server health check (server name, msad version, connectivity) |
|
|
36
|
+
|
|
37
|
+
The `find_users`, `find_groups`, `find_computers` and `find_ous` tools accept an
|
|
38
|
+
optional `base` (a DN, e.g. an OU) to restrict the search to that subtree
|
|
39
|
+
instead of the whole domain.
|
|
40
|
+
|
|
41
|
+
### Returned attributes
|
|
42
|
+
|
|
43
|
+
By default `get_user` / `find_users` return a useful attribute set: identity
|
|
44
|
+
fields plus `manager` — the **distinguished name (DN)** of the user's manager,
|
|
45
|
+
e.g. `CN=Anna Bianchi,OU=Staff,DC=group,DC=example,DC=com` — as well as
|
|
46
|
+
`memberOf` (direct group DNs), `userAccountControl`, `accountExpires`,
|
|
47
|
+
`lastLogonTimestamp` and `whenCreated`. Group lookups include `managedBy` (the
|
|
48
|
+
DN of the group's owner), `member`, `groupType` and `whenCreated`.
|
|
49
|
+
|
|
50
|
+
To expand a manager (or any DN-valued field) into a full record, call
|
|
51
|
+
`get_by_dn` with that DN. This is a direct, efficient lookup (the DN is used as
|
|
52
|
+
the search base), so an agent can do: `get_user("mrossi")` → read `manager` →
|
|
53
|
+
`get_by_dn("<that DN>")`.
|
|
54
|
+
|
|
55
|
+
## Authentication & connection
|
|
56
|
+
|
|
57
|
+
The server has **no connection settings of its own**: it reuses the `msad`
|
|
58
|
+
configuration file, `~/.msad.toml` by default (create it with `msad init`).
|
|
59
|
+
Each tool call opens a short-lived connection through `msad.connect()`.
|
|
60
|
+
|
|
61
|
+
### Domain parameters (`~/.msad.toml`)
|
|
62
|
+
|
|
63
|
+
```toml
|
|
64
|
+
[defaults]
|
|
65
|
+
domain = "group" # used when a tool call omits `domain`
|
|
66
|
+
|
|
67
|
+
[domains.group]
|
|
68
|
+
host = "dc.example.com" # hostname only (no scheme, no :port)
|
|
69
|
+
base = "dc=group,dc=example,dc=com"
|
|
70
|
+
port = 636 # default: 389
|
|
71
|
+
use_ssl = true # default: false (true = LDAPS)
|
|
72
|
+
# user = "svc_account" # optional (see auth below)
|
|
73
|
+
# password = "..." # optional
|
|
74
|
+
|
|
75
|
+
# A second domain (here using user/password auth):
|
|
76
|
+
[domains.lab]
|
|
77
|
+
host = "dc.lab.example.com"
|
|
78
|
+
base = "dc=lab,dc=example,dc=com"
|
|
79
|
+
port = 636
|
|
80
|
+
use_ssl = true
|
|
81
|
+
user = "svc_reader"
|
|
82
|
+
password = "s3cr3t"
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
You can declare several `[domains.<name>]` blocks and pick one per call with the
|
|
86
|
+
tool's `domain` argument, or globally via `MSAD_DOMAIN`. For example, an agent
|
|
87
|
+
can call `find_users(surname="Rossi", domain="lab")` to target the `lab` domain
|
|
88
|
+
while `[defaults].domain` stays `group`.
|
|
89
|
+
|
|
90
|
+
### Overrides via environment
|
|
91
|
+
|
|
92
|
+
- `MSAD_DOMAIN` — default domain when a tool call omits `domain`
|
|
93
|
+
- `MSAD_CONFIG_FILE` — path to an alternative TOML config
|
|
94
|
+
|
|
95
|
+
### Authentication modes
|
|
96
|
+
|
|
97
|
+
The mode is chosen **automatically** from the domain block:
|
|
98
|
+
|
|
99
|
+
- **Kerberos (SASL)** — when `user`/`password` are *not both* set (the default).
|
|
100
|
+
Obtain a ticket first:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
kinit # or: kinit <user>@REALM
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The server relies on the system Kerberos ticket cache (or a keytab via
|
|
107
|
+
`KRB5_CLIENT_KTNAME`). If the ticket is missing or expired, tools fail with a
|
|
108
|
+
clean `MsadConnectionError` message. When running as a background/remote
|
|
109
|
+
service, make sure that process can see a valid ticket or keytab.
|
|
110
|
+
|
|
111
|
+
- **User / password** — when **both** `user` and `password` are set. Simple LDAP
|
|
112
|
+
bind. The password is stored in clear text in the TOML, so restrict the file
|
|
113
|
+
permissions (`chmod 600 ~/.msad.toml`).
|
|
114
|
+
|
|
115
|
+
> Note: setting only one of `user`/`password` silently falls back to Kerberos.
|
|
116
|
+
> Set both, or neither.
|
|
117
|
+
|
|
118
|
+
Use LDAPS (`port = 636`, `use_ssl = true`) whenever possible.
|
|
119
|
+
|
|
120
|
+
## Running
|
|
121
|
+
|
|
122
|
+
Using uvx:
|
|
123
|
+
|
|
124
|
+
uvx --from git+https://github.com/matteoredaelli/mcpAD mcpAD
|
|
125
|
+
|
|
126
|
+
The `Makefile` wraps the common cases. Transport, host and port are
|
|
127
|
+
configurable:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
make start-stdio # stdio (for local MCP clients)
|
|
131
|
+
make start-http # streamable-http on 127.0.0.1:8000
|
|
132
|
+
make start-http HOST=0.0.0.0 PORT=9000 # bind elsewhere
|
|
133
|
+
make start-sse # sse transport
|
|
134
|
+
make start TRANSPORT=streamable-http PORT=9000 # generic form
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Equivalent raw commands (the server reads `MCP_TRANSPORT` / `MCP_HOST` /
|
|
138
|
+
`MCP_PORT` from the environment):
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
uv run mcpad # stdio (default)
|
|
142
|
+
MCP_TRANSPORT=streamable-http MCP_PORT=9000 uv run mcpad
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
## Registering the server with an MCP client / agent
|
|
147
|
+
|
|
148
|
+
MCP clients (Claude Desktop, IDE agents, custom agents, ...) usually accept a
|
|
149
|
+
JSON config with a `mcpServers` map. Two deployment styles:
|
|
150
|
+
|
|
151
|
+
### Local (stdio) — the client launches the server
|
|
152
|
+
|
|
153
|
+
The client spawns the process and talks to it over stdio. This is the simplest
|
|
154
|
+
setup and keeps everything on your machine (including your Kerberos ticket).
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"mcpServers": {
|
|
159
|
+
"mcpAD": {
|
|
160
|
+
"command": "uv",
|
|
161
|
+
"args": [
|
|
162
|
+
"run",
|
|
163
|
+
"--directory", "/path/to/mcpAD",
|
|
164
|
+
"mcpad"
|
|
165
|
+
],
|
|
166
|
+
"env": {
|
|
167
|
+
"MSAD_DOMAIN": "group"
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Notes:
|
|
175
|
+
- `--directory` makes `uv` use this project's environment regardless of the
|
|
176
|
+
client's working directory.
|
|
177
|
+
- Kerberos: the spawned process inherits your environment, so a ticket obtained
|
|
178
|
+
with `kinit` in the same user session is used automatically. For an unattended
|
|
179
|
+
client, point it at a keytab (e.g. add `"KRB5_CLIENT_KTNAME": "/path/to.keytab"`
|
|
180
|
+
to `env`).
|
|
181
|
+
|
|
182
|
+
### Remote (streamable-http) — the server runs as a service
|
|
183
|
+
|
|
184
|
+
Start the server as a long-running HTTP service, then point the client at its
|
|
185
|
+
URL. Useful when the server runs on a host that has AD/Kerberos access while the
|
|
186
|
+
client runs elsewhere.
|
|
187
|
+
|
|
188
|
+
Start the service:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
make start-http HOST=0.0.0.0 PORT=9000
|
|
192
|
+
# serves the MCP endpoint at http://<host>:9000/mcp
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Client config referencing the URL:
|
|
196
|
+
|
|
197
|
+
```json
|
|
198
|
+
{
|
|
199
|
+
"mcpServers": {
|
|
200
|
+
"mcpAD": {
|
|
201
|
+
"transport": "http",
|
|
202
|
+
"url": "http://mcp-host.example.com:9000/mcp"
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
Notes:
|
|
209
|
+
- The default streamable-http path is `/mcp`.
|
|
210
|
+
- The server itself performs no client authentication; if you expose it beyond
|
|
211
|
+
localhost, put it behind a reverse proxy / network controls and treat the AD
|
|
212
|
+
credentials on that host accordingly.
|
|
213
|
+
- Kerberos runs where the **server** runs: that host needs a valid ticket or a
|
|
214
|
+
keytab, not the client.
|
|
215
|
+
|
|
216
|
+
## Development
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
uv sync
|
|
220
|
+
uv run python -c "import asyncio; from mcpad import mcp; print(asyncio.run(mcp.list_tools()))"
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
The [`msad`](https://github.com/matteoredaelli/msad) dependency can be installed
|
|
224
|
+
from its Git repository, or as an editable local path during development so that
|
|
225
|
+
library changes are picked up immediately.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "mcpad"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "A FastMCP server exposing the msad Active Directory / LDAP library"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "GPL-3.0-or-later"
|
|
7
|
+
keywords = [
|
|
8
|
+
"active-directory",
|
|
9
|
+
"ldap",
|
|
10
|
+
"mcp",
|
|
11
|
+
"kerberos",
|
|
12
|
+
"ad",
|
|
13
|
+
]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: System Administrators",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Programming Language :: Python :: 3.14",
|
|
24
|
+
"Topic :: System :: Systems Administration :: Authentication/Directory :: LDAP",
|
|
25
|
+
]
|
|
26
|
+
requires-python = ">=3.11"
|
|
27
|
+
dependencies = [
|
|
28
|
+
"fastmcp>=4.0.9",
|
|
29
|
+
"msad>=0.6.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[[project.authors]]
|
|
33
|
+
name = "Matteo Redaelli"
|
|
34
|
+
email = "matteo.redaelli@gmail.com"
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Homepage = "https://github.com/matteoredaelli/mcpAD"
|
|
38
|
+
Repository = "https://github.com/matteoredaelli/mcpAD"
|
|
39
|
+
Issues = "https://github.com/matteoredaelli/mcpAD/issues"
|
|
40
|
+
|
|
41
|
+
[project.scripts]
|
|
42
|
+
mcpad = "mcpad:main"
|
|
43
|
+
|
|
44
|
+
[tool.uv.sources]
|
|
45
|
+
|
|
46
|
+
[tool.ruff]
|
|
47
|
+
target-version = "py311"
|
|
48
|
+
src = ["src"]
|
|
49
|
+
line-length = 100
|
|
50
|
+
|
|
51
|
+
[tool.ruff.lint]
|
|
52
|
+
select = [
|
|
53
|
+
"E",
|
|
54
|
+
"F",
|
|
55
|
+
"I",
|
|
56
|
+
"UP",
|
|
57
|
+
"B",
|
|
58
|
+
"W",
|
|
59
|
+
]
|
|
60
|
+
|
|
61
|
+
[tool.ruff.format]
|
|
62
|
+
docstring-code-format = true
|
|
63
|
+
|
|
64
|
+
[tool.pyrefly]
|
|
65
|
+
project-includes = ["src"]
|
|
66
|
+
python-version = "3.11"
|
|
67
|
+
preset = "strict"
|
|
68
|
+
|
|
69
|
+
[build-system]
|
|
70
|
+
requires = ["uv_build>=0.12.19,<0.13.0"]
|
|
71
|
+
build-backend = "uv_build"
|
|
72
|
+
|
|
73
|
+
[dependency-groups]
|
|
74
|
+
dev = [
|
|
75
|
+
"ruff>=0.16",
|
|
76
|
+
"pyrefly>=0.16",
|
|
77
|
+
]
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Copyright 2026 Matteo Redaelli
|
|
2
|
+
# mcpAD - MCP server for Active Directory / LDAP (built on msad)
|
|
3
|
+
# Copyright (C) 2026 - matteo.redaelli@gmail.com
|
|
4
|
+
#
|
|
5
|
+
# This program is free software: you can redistribute it and/or modify
|
|
6
|
+
# it under the terms of the GNU General Public License as published by
|
|
7
|
+
# the Free Software Foundation, either version 3 of the License, or
|
|
8
|
+
# (at your option) any later version.
|
|
9
|
+
#
|
|
10
|
+
# This program is distributed in the hope that it will be useful,
|
|
11
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
13
|
+
# GNU General Public License for more details.
|
|
14
|
+
#
|
|
15
|
+
# You should have received a copy of the GNU General Public License
|
|
16
|
+
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
17
|
+
|
|
18
|
+
[project]
|
|
19
|
+
name = "mcpad"
|
|
20
|
+
version = "0.1.0"
|
|
21
|
+
description = "A FastMCP server exposing the msad Active Directory / LDAP library"
|
|
22
|
+
readme = "README.md"
|
|
23
|
+
license = "GPL-3.0-or-later"
|
|
24
|
+
authors = [
|
|
25
|
+
{ name = "Matteo Redaelli", email = "matteo.redaelli@gmail.com" }
|
|
26
|
+
]
|
|
27
|
+
keywords = ["active-directory", "ldap", "mcp", "kerberos", "ad"]
|
|
28
|
+
classifiers = [
|
|
29
|
+
"Development Status :: 4 - Beta",
|
|
30
|
+
"Environment :: Console",
|
|
31
|
+
"Intended Audience :: System Administrators",
|
|
32
|
+
"Operating System :: OS Independent",
|
|
33
|
+
"Programming Language :: Python :: 3",
|
|
34
|
+
"Programming Language :: Python :: 3.11",
|
|
35
|
+
"Programming Language :: Python :: 3.12",
|
|
36
|
+
"Programming Language :: Python :: 3.13",
|
|
37
|
+
"Programming Language :: Python :: 3.14",
|
|
38
|
+
"Topic :: System :: Systems Administration :: Authentication/Directory :: LDAP",
|
|
39
|
+
]
|
|
40
|
+
requires-python = ">=3.11"
|
|
41
|
+
dependencies = [
|
|
42
|
+
"fastmcp>=4.0.9",
|
|
43
|
+
"msad>=0.6.0"
|
|
44
|
+
#"msad @ git+https://github.com/matteoredaelli/msad.git"
|
|
45
|
+
]
|
|
46
|
+
|
|
47
|
+
[project.urls]
|
|
48
|
+
Homepage = "https://github.com/matteoredaelli/mcpAD"
|
|
49
|
+
Repository = "https://github.com/matteoredaelli/mcpAD"
|
|
50
|
+
Issues = "https://github.com/matteoredaelli/mcpAD/issues"
|
|
51
|
+
|
|
52
|
+
[project.scripts]
|
|
53
|
+
mcpad = "mcpad:main"
|
|
54
|
+
|
|
55
|
+
[tool.uv.sources]
|
|
56
|
+
# Development-only override: use the local msad checkout. This is NOT included
|
|
57
|
+
# in the published package; installers resolve `msad>=0.5.0` from the index.
|
|
58
|
+
# msad = { path = "/tmp/Downloads/github/msad", editable = true }
|
|
59
|
+
|
|
60
|
+
[build-system]
|
|
61
|
+
requires = ["uv_build>=0.12.19,<0.13.0"]
|
|
62
|
+
build-backend = "uv_build"
|
|
63
|
+
|
|
64
|
+
[dependency-groups]
|
|
65
|
+
dev = [
|
|
66
|
+
"ruff>=0.16",
|
|
67
|
+
"pyrefly>=0.16",
|
|
68
|
+
]
|
|
69
|
+
|
|
70
|
+
[tool.ruff]
|
|
71
|
+
target-version = "py311"
|
|
72
|
+
src = ["src"]
|
|
73
|
+
line-length = 100
|
|
74
|
+
|
|
75
|
+
[tool.ruff.lint]
|
|
76
|
+
select = [
|
|
77
|
+
"E", # pycodestyle errors
|
|
78
|
+
"F", # pyflakes
|
|
79
|
+
"I", # isort
|
|
80
|
+
"UP", # pyupgrade
|
|
81
|
+
"B", # flake8-bugbear
|
|
82
|
+
"W", # pycodestyle warnings
|
|
83
|
+
]
|
|
84
|
+
|
|
85
|
+
[tool.ruff.format]
|
|
86
|
+
docstring-code-format = true
|
|
87
|
+
|
|
88
|
+
[tool.pyrefly]
|
|
89
|
+
project-includes = ["src"]
|
|
90
|
+
python-version = "3.11"
|
|
91
|
+
preset = "strict"
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Copyright 2026 Matteo Redaelli
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
# you may not use this file except in compliance with the License.
|
|
5
|
+
# You may obtain a copy of the License at
|
|
6
|
+
#
|
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
#
|
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
# See the License for the specific language governing permissions and
|
|
13
|
+
# limitations under the License.
|
|
14
|
+
|
|
15
|
+
"""mcpAD: a FastMCP server exposing the msad Active Directory library."""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from .server import main, mcp
|
|
20
|
+
|
|
21
|
+
__all__ = ["main", "mcp"]
|
|
@@ -0,0 +1,397 @@
|
|
|
1
|
+
# Copyright 2026 Matteo Redaelli
|
|
2
|
+
# mcpAD - MCP server for Active Directory / LDAP (built on msad)
|
|
3
|
+
# Copyright (C) 2026 - matteo.redaelli@gmail.com
|
|
4
|
+
#
|
|
5
|
+
# This program is free software: you can redistribute it and/or modify
|
|
6
|
+
# it under the terms of the GNU General Public License as published by
|
|
7
|
+
# the Free Software Foundation, either version 3 of the License, or
|
|
8
|
+
# (at your option) any later version.
|
|
9
|
+
#
|
|
10
|
+
# This program is distributed in the hope that it will be useful,
|
|
11
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
13
|
+
# GNU General Public License for more details.
|
|
14
|
+
#
|
|
15
|
+
# You should have received a copy of the GNU General Public License
|
|
16
|
+
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
17
|
+
|
|
18
|
+
"""FastMCP server exposing the msad Active Directory / LDAP library as MCP tools.
|
|
19
|
+
|
|
20
|
+
Each tool opens a short-lived connection using the msad configuration
|
|
21
|
+
(``~/.msad.toml`` by default, or the ``MSAD_DOMAIN`` / ``MSAD_CONFIG_FILE``
|
|
22
|
+
environment variables) and calls the corresponding msad library function.
|
|
23
|
+
|
|
24
|
+
Run it with:
|
|
25
|
+
|
|
26
|
+
uv run mcpad # stdio transport (for MCP clients)
|
|
27
|
+
fastmcp run src/mcpad/server.py
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
from __future__ import annotations
|
|
31
|
+
|
|
32
|
+
import datetime
|
|
33
|
+
import os
|
|
34
|
+
from typing import Any
|
|
35
|
+
|
|
36
|
+
import msad
|
|
37
|
+
from fastmcp import FastMCP
|
|
38
|
+
from msad.exceptions import MsadError
|
|
39
|
+
|
|
40
|
+
mcp: FastMCP = FastMCP(
|
|
41
|
+
name="mcpAD",
|
|
42
|
+
instructions=(
|
|
43
|
+
"Query Active Directory / LDAP via the msad library: search users and "
|
|
44
|
+
"groups, inspect memberships, and check account status. All tools are "
|
|
45
|
+
"read-only."
|
|
46
|
+
),
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
# Default domain / config file can be overridden per environment.
|
|
50
|
+
_DEFAULT_DOMAIN = os.environ.get("MSAD_DOMAIN") or None
|
|
51
|
+
_CONFIG_FILE = os.environ.get("MSAD_CONFIG_FILE") or None
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _jsonable(value: Any) -> Any:
|
|
55
|
+
"""Make LDAP values JSON-serializable (datetimes -> ISO strings)."""
|
|
56
|
+
if isinstance(value, datetime.datetime):
|
|
57
|
+
return value.isoformat()
|
|
58
|
+
if isinstance(value, dict):
|
|
59
|
+
return {k: _jsonable(v) for k, v in value.items()}
|
|
60
|
+
if isinstance(value, list):
|
|
61
|
+
return [_jsonable(v) for v in value]
|
|
62
|
+
if isinstance(value, bytes):
|
|
63
|
+
return value.decode("utf-8", errors="replace")
|
|
64
|
+
return value
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
class _Session:
|
|
68
|
+
"""Resolve config and open a bound connection, raising MsadError on failure."""
|
|
69
|
+
|
|
70
|
+
def __init__(self, domain: str | None) -> None:
|
|
71
|
+
self.config = msad.load_domain_config(domain or _DEFAULT_DOMAIN, _CONFIG_FILE)
|
|
72
|
+
self.conn = msad.connect(self.config)
|
|
73
|
+
|
|
74
|
+
@property
|
|
75
|
+
def base(self) -> str:
|
|
76
|
+
return self.config.base
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
@mcp.tool
|
|
80
|
+
def test_connection(domain: str | None = None) -> dict[str, Any]:
|
|
81
|
+
"""Test connectivity and bind to the AD server without raising.
|
|
82
|
+
|
|
83
|
+
Returns a status dict with `ok`, `target`, `auth` and `error`. Use this to
|
|
84
|
+
verify the configuration and reachability before running other tools.
|
|
85
|
+
"""
|
|
86
|
+
config = msad.load_domain_config(domain or _DEFAULT_DOMAIN, _CONFIG_FILE)
|
|
87
|
+
return _jsonable(msad.check_connection(config))
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
@mcp.tool
|
|
91
|
+
def health(domain: str | None = None) -> dict[str, Any]:
|
|
92
|
+
"""Server health check: reports server name, msad version and AD connectivity."""
|
|
93
|
+
result: dict[str, Any] = {
|
|
94
|
+
"server": mcp.name,
|
|
95
|
+
"msad_version": msad.__version__,
|
|
96
|
+
}
|
|
97
|
+
try:
|
|
98
|
+
config = msad.load_domain_config(domain or _DEFAULT_DOMAIN, _CONFIG_FILE)
|
|
99
|
+
result["connection"] = _jsonable(msad.check_connection(config))
|
|
100
|
+
except MsadError as exc:
|
|
101
|
+
# Config could not be loaded (missing file, unknown domain, ...).
|
|
102
|
+
result["connection"] = {"ok": False, "error": str(exc)}
|
|
103
|
+
result["ok"] = bool(result["connection"].get("ok"))
|
|
104
|
+
return result
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
@mcp.tool
|
|
108
|
+
def find_users(
|
|
109
|
+
name: str | None = None,
|
|
110
|
+
surname: str | None = None,
|
|
111
|
+
mail: str | None = None,
|
|
112
|
+
sam: str | None = None,
|
|
113
|
+
department: str | None = None,
|
|
114
|
+
base: str | None = None,
|
|
115
|
+
limit: int = 100,
|
|
116
|
+
domain: str | None = None,
|
|
117
|
+
) -> list[dict[str, Any]]:
|
|
118
|
+
"""Find AD users by field. Criteria are ANDed; values may contain * wildcards.
|
|
119
|
+
|
|
120
|
+
Pass `base` (a DN, e.g. an OU) to restrict the search to a subtree.
|
|
121
|
+
"""
|
|
122
|
+
s = _Session(domain)
|
|
123
|
+
result = msad.find_users(
|
|
124
|
+
s.conn,
|
|
125
|
+
base or s.base,
|
|
126
|
+
name=name,
|
|
127
|
+
surname=surname,
|
|
128
|
+
mail=mail,
|
|
129
|
+
sam=sam,
|
|
130
|
+
department=department,
|
|
131
|
+
limit=limit,
|
|
132
|
+
)
|
|
133
|
+
return _jsonable(result)
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
@mcp.tool
|
|
137
|
+
def get_user(identifier: str, domain: str | None = None) -> dict[str, Any] | None:
|
|
138
|
+
"""Get a single AD user by sAMAccountName, UPN, mail or cn (exact match)."""
|
|
139
|
+
s = _Session(domain)
|
|
140
|
+
return _jsonable(msad.get_user(s.conn, s.base, identifier))
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
@mcp.tool
|
|
144
|
+
def find_groups(
|
|
145
|
+
string: str, base: str | None = None, limit: int = 100, domain: str | None = None
|
|
146
|
+
) -> list[dict[str, Any]]:
|
|
147
|
+
"""Find AD groups by cn/name/sAMAccountName/displayName (supports * wildcards).
|
|
148
|
+
|
|
149
|
+
Pass `base` (a DN, e.g. an OU) to restrict the search to a subtree.
|
|
150
|
+
"""
|
|
151
|
+
s = _Session(domain)
|
|
152
|
+
return _jsonable(msad.find_groups(s.conn, base or s.base, string, limit=limit))
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
@mcp.tool
|
|
156
|
+
def get_group(identifier: str, domain: str | None = None) -> dict[str, Any] | None:
|
|
157
|
+
"""Get a single AD group by sAMAccountName or cn (exact match)."""
|
|
158
|
+
s = _Session(domain)
|
|
159
|
+
return _jsonable(msad.get_group(s.conn, s.base, identifier))
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
@mcp.tool
|
|
163
|
+
def get_by_dn(dn: str, domain: str | None = None) -> dict[str, Any] | None:
|
|
164
|
+
"""Fetch any AD entry directly by its distinguished name (DN).
|
|
165
|
+
|
|
166
|
+
Use this to resolve DN-valued attributes into full records, e.g. the
|
|
167
|
+
`manager` of a user or the `managedBy` owner of a group. Returns None if
|
|
168
|
+
the DN does not exist.
|
|
169
|
+
"""
|
|
170
|
+
s = _Session(domain)
|
|
171
|
+
return _jsonable(msad.get_by_dn(s.conn, dn))
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
@mcp.tool
|
|
175
|
+
def find_computers(
|
|
176
|
+
name: str | None = None,
|
|
177
|
+
dns: str | None = None,
|
|
178
|
+
os: str | None = None,
|
|
179
|
+
base: str | None = None,
|
|
180
|
+
limit: int = 100,
|
|
181
|
+
domain: str | None = None,
|
|
182
|
+
) -> list[dict[str, Any]]:
|
|
183
|
+
"""Find AD computers by cn (name), dNSHostName (dns) or operatingSystem (os).
|
|
184
|
+
|
|
185
|
+
Criteria are ANDed; values may contain * wildcards. Pass `base` (a DN, e.g.
|
|
186
|
+
an OU) to restrict the search to a subtree.
|
|
187
|
+
"""
|
|
188
|
+
s = _Session(domain)
|
|
189
|
+
return _jsonable(
|
|
190
|
+
msad.find_computers(s.conn, base or s.base, name=name, dns=dns, os=os, limit=limit)
|
|
191
|
+
)
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
@mcp.tool
|
|
195
|
+
def get_computer(identifier: str, domain: str | None = None) -> dict[str, Any] | None:
|
|
196
|
+
"""Get a single AD computer by sAMAccountName, cn or dNSHostName (exact match)."""
|
|
197
|
+
s = _Session(domain)
|
|
198
|
+
return _jsonable(msad.get_computer(s.conn, s.base, identifier))
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
@mcp.tool
|
|
202
|
+
def find_ous(
|
|
203
|
+
name: str | None = None,
|
|
204
|
+
base: str | None = None,
|
|
205
|
+
limit: int = 100,
|
|
206
|
+
domain: str | None = None,
|
|
207
|
+
) -> list[dict[str, Any]]:
|
|
208
|
+
"""Find AD organizational units (OUs) by name (matches `ou`; may contain *).
|
|
209
|
+
|
|
210
|
+
Pass `base` (a DN) to search under a specific parent OU instead of the
|
|
211
|
+
whole domain.
|
|
212
|
+
"""
|
|
213
|
+
s = _Session(domain)
|
|
214
|
+
return _jsonable(msad.find_ous(s.conn, base or s.base, name=name, limit=limit))
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
@mcp.tool
|
|
218
|
+
def get_ou(identifier: str, domain: str | None = None) -> dict[str, Any] | None:
|
|
219
|
+
"""Get a single AD organizational unit by its `ou` name or full DN (exact)."""
|
|
220
|
+
s = _Session(domain)
|
|
221
|
+
return _jsonable(msad.get_ou(s.conn, s.base, identifier))
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
@mcp.tool
|
|
225
|
+
def get_ou_contents(
|
|
226
|
+
ou_dn: str,
|
|
227
|
+
object_class: str | None = None,
|
|
228
|
+
limit: int = 1000,
|
|
229
|
+
domain: str | None = None,
|
|
230
|
+
) -> list[dict[str, Any]]:
|
|
231
|
+
"""List the objects contained under an OU (given its DN).
|
|
232
|
+
|
|
233
|
+
Optionally restrict to a single `object_class` (e.g. user, group, computer,
|
|
234
|
+
organizationalUnit). Returns an empty list if the OU DN does not exist.
|
|
235
|
+
"""
|
|
236
|
+
s = _Session(domain)
|
|
237
|
+
return _jsonable(msad.get_ou_contents(s.conn, ou_dn, object_class=object_class, limit=limit))
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
@mcp.tool
|
|
241
|
+
def find_inactive_users(
|
|
242
|
+
days: int = 90,
|
|
243
|
+
base: str | None = None,
|
|
244
|
+
include_never: bool = False,
|
|
245
|
+
limit: int = 100,
|
|
246
|
+
domain: str | None = None,
|
|
247
|
+
) -> list[dict[str, Any]]:
|
|
248
|
+
"""Find users whose last logon is older than `days` (default 90).
|
|
249
|
+
|
|
250
|
+
Matches `lastLogonTimestamp` at or before the cutoff. Set
|
|
251
|
+
`include_never=True` to also return users that never logged on. Pass
|
|
252
|
+
`base` (a DN) to scope to an OU.
|
|
253
|
+
"""
|
|
254
|
+
s = _Session(domain)
|
|
255
|
+
return _jsonable(
|
|
256
|
+
msad.find_inactive_users(
|
|
257
|
+
s.conn, base or s.base, days=days, include_never=include_never, limit=limit
|
|
258
|
+
)
|
|
259
|
+
)
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
@mcp.tool
|
|
263
|
+
def find_stale_computers(
|
|
264
|
+
days: int = 90,
|
|
265
|
+
base: str | None = None,
|
|
266
|
+
include_never: bool = False,
|
|
267
|
+
limit: int = 100,
|
|
268
|
+
domain: str | None = None,
|
|
269
|
+
) -> list[dict[str, Any]]:
|
|
270
|
+
"""Find computers whose last logon is older than `days` (default 90).
|
|
271
|
+
|
|
272
|
+
Matches `lastLogonTimestamp` at or before the cutoff. Set
|
|
273
|
+
`include_never=True` to also return computers that never logged on. Pass
|
|
274
|
+
`base` (a DN) to scope to an OU.
|
|
275
|
+
"""
|
|
276
|
+
s = _Session(domain)
|
|
277
|
+
return _jsonable(
|
|
278
|
+
msad.find_stale_computers(
|
|
279
|
+
s.conn, base or s.base, days=days, include_never=include_never, limit=limit
|
|
280
|
+
)
|
|
281
|
+
)
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
@mcp.tool
|
|
285
|
+
def get_domain_info(domain: str | None = None) -> dict[str, Any] | None:
|
|
286
|
+
"""Read the domain object: security-relevant settings and metadata (audit)."""
|
|
287
|
+
s = _Session(domain)
|
|
288
|
+
return _jsonable(msad.get_domain_info(s.conn, s.base))
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
@mcp.tool
|
|
292
|
+
def get_password_policy(domain: str | None = None) -> dict[str, Any] | None:
|
|
293
|
+
"""Read the default domain password policy (maxPwdAge, minPwdLength, ...)."""
|
|
294
|
+
s = _Session(domain)
|
|
295
|
+
return _jsonable(msad.get_password_policy(s.conn, s.base))
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
@mcp.tool
|
|
299
|
+
def get_password_policy_violations(
|
|
300
|
+
include_never_set: bool = True,
|
|
301
|
+
limit: int = 100,
|
|
302
|
+
domain: str | None = None,
|
|
303
|
+
) -> list[dict[str, Any]]:
|
|
304
|
+
"""Find users whose password violates the domain policy (audit).
|
|
305
|
+
|
|
306
|
+
Flags enabled users whose password has expired (older than the domain
|
|
307
|
+
`maxPwdAge`) and, when `include_never_set` is True, users who must set a
|
|
308
|
+
password at next logon (`pwdLastSet=0`). Accounts whose password never
|
|
309
|
+
expires are excluded. Returns an empty list if the domain has no maximum
|
|
310
|
+
password age.
|
|
311
|
+
"""
|
|
312
|
+
s = _Session(domain)
|
|
313
|
+
return _jsonable(
|
|
314
|
+
msad.get_password_policy_violations(
|
|
315
|
+
s.conn, s.base, include_never_set=include_never_set, limit=limit
|
|
316
|
+
)
|
|
317
|
+
)
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
@mcp.tool
|
|
321
|
+
def get_privileged_groups(
|
|
322
|
+
with_members: bool = False,
|
|
323
|
+
nested: bool = False,
|
|
324
|
+
domain: str | None = None,
|
|
325
|
+
) -> list[dict[str, Any]]:
|
|
326
|
+
"""Report on well-known privileged groups (Domain Admins, ...) with counts.
|
|
327
|
+
|
|
328
|
+
Each entry includes the group's attributes plus `member_count`. Set
|
|
329
|
+
`with_members=True` to include a `members` list (use `nested=True` to
|
|
330
|
+
expand nested membership).
|
|
331
|
+
"""
|
|
332
|
+
s = _Session(domain)
|
|
333
|
+
return _jsonable(
|
|
334
|
+
msad.get_privileged_groups(s.conn, s.base, with_members=with_members, nested=nested)
|
|
335
|
+
)
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
@mcp.tool
|
|
339
|
+
def group_members(
|
|
340
|
+
group: str, nested: bool = False, limit: int = 1000, domain: str | None = None
|
|
341
|
+
) -> list[dict[str, Any]]:
|
|
342
|
+
"""List members of a group. Set nested=True for recursive membership."""
|
|
343
|
+
s = _Session(domain)
|
|
344
|
+
return _jsonable(msad.group_members(s.conn, s.base, group, nested=nested, limit=limit))
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
@mcp.tool
|
|
348
|
+
def user_groups(
|
|
349
|
+
user: str, nested: bool = True, limit: int = 1000, domain: str | None = None
|
|
350
|
+
) -> list[dict[str, Any]] | None:
|
|
351
|
+
"""List the groups a user belongs to (nested/recursive by default)."""
|
|
352
|
+
s = _Session(domain)
|
|
353
|
+
return _jsonable(msad.user_groups(s.conn, s.base, limit, user, nested=nested))
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
@mcp.tool
|
|
357
|
+
def is_member(group: str, user: str, domain: str | None = None) -> bool:
|
|
358
|
+
"""Return True if the user is a (nested) member of the group."""
|
|
359
|
+
s = _Session(domain)
|
|
360
|
+
return msad.is_member(s.conn, s.base, group, user)
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
@mcp.tool
|
|
364
|
+
def is_disabled(user: str, domain: str | None = None) -> bool | None:
|
|
365
|
+
"""Return True if the account is disabled, None if the user is not found."""
|
|
366
|
+
s = _Session(domain)
|
|
367
|
+
return msad.is_disabled(s.conn, s.base, user)
|
|
368
|
+
|
|
369
|
+
|
|
370
|
+
@mcp.tool
|
|
371
|
+
def is_locked(user: str, domain: str | None = None) -> bool | None:
|
|
372
|
+
"""Return True if the account is locked, None if the user is not found."""
|
|
373
|
+
s = _Session(domain)
|
|
374
|
+
return msad.is_locked(s.conn, s.base, user)
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
def main() -> None:
|
|
378
|
+
"""Entry point. Transport/host/port are read from the environment.
|
|
379
|
+
|
|
380
|
+
- MCP_TRANSPORT: "stdio" (default), "http", "sse" or "streamable-http"
|
|
381
|
+
- MCP_HOST: bind host for HTTP transports (default 127.0.0.1)
|
|
382
|
+
- MCP_PORT: bind port for HTTP transports (default 8000)
|
|
383
|
+
"""
|
|
384
|
+
transport = os.environ.get("MCP_TRANSPORT", "stdio")
|
|
385
|
+
if transport == "stdio":
|
|
386
|
+
mcp.run(transport="stdio")
|
|
387
|
+
else:
|
|
388
|
+
host = os.environ.get("MCP_HOST", "127.0.0.1")
|
|
389
|
+
port = int(os.environ.get("MCP_PORT", "8000"))
|
|
390
|
+
mcp.run(transport=transport, host=host, port=port) # type: ignore[arg-type]
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
if __name__ == "__main__":
|
|
394
|
+
main()
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
__all__ = ["mcp", "main", "MsadError"]
|