mcpad 0.1.0__py3-none-any.whl

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/__init__.py ADDED
@@ -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"]
mcpad/server.py ADDED
@@ -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"]
@@ -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.
@@ -0,0 +1,6 @@
1
+ mcpad/__init__.py,sha256=dOpH_5JbJk6kn3sjfBeXqrClrOKoaaQrggfJZiCAysM,748
2
+ mcpad/server.py,sha256=uyI5QIXShMrNcbdOJBbG07bpxO9Q3K8gunMTJrjAL00,13097
3
+ mcpad-0.1.0.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
4
+ mcpad-0.1.0.dist-info/entry_points.txt,sha256=Wpg6ZopZN2lgZorlUR00d-y_MNfvXhOo9MydRRxUSgg,38
5
+ mcpad-0.1.0.dist-info/METADATA,sha256=EFJgS-tAT2L2yt3WeeS0ta148cMDZWhtgqX08DAhbIQ,9344
6
+ mcpad-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.1
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ mcpad = mcpad:main
3
+