mac-diagnostics-mcp 0.5.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.
Files changed (36) hide show
  1. mac_diagnostics_mcp-0.5.0/LICENSE +21 -0
  2. mac_diagnostics_mcp-0.5.0/PKG-INFO +322 -0
  3. mac_diagnostics_mcp-0.5.0/README.md +300 -0
  4. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/__init__.py +0 -0
  5. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/runner.py +129 -0
  6. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/lib-assess.sh +68 -0
  7. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/lib-findings.sh +59 -0
  8. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-backup.sh +210 -0
  9. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-battery.sh +203 -0
  10. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-cpu-memory.sh +265 -0
  11. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-crashes.sh +399 -0
  12. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-disk-health.sh +227 -0
  13. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-mcp-servers.sh +452 -0
  14. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-network.sh +218 -0
  15. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-node-packages.sh +272 -0
  16. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-node-update.sh +328 -0
  17. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-quick-health.sh +216 -0
  18. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-security.sh +291 -0
  19. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh +305 -0
  20. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-software-update.sh +241 -0
  21. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-startup-items.sh +238 -0
  22. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-storage.sh +215 -0
  23. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-wifi.sh +204 -0
  24. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/server.py +456 -0
  25. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/state.py +150 -0
  26. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/triage.py +182 -0
  27. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/PKG-INFO +322 -0
  28. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/SOURCES.txt +34 -0
  29. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/dependency_links.txt +1 -0
  30. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/entry_points.txt +2 -0
  31. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/requires.txt +5 -0
  32. mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/top_level.txt +1 -0
  33. mac_diagnostics_mcp-0.5.0/pyproject.toml +54 -0
  34. mac_diagnostics_mcp-0.5.0/setup.cfg +4 -0
  35. mac_diagnostics_mcp-0.5.0/tests/test_runner.py +446 -0
  36. mac_diagnostics_mcp-0.5.0/tests/test_server.py +212 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Thomas Juul Dyhr
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.
@@ -0,0 +1,322 @@
1
+ Metadata-Version: 2.4
2
+ Name: mac-diagnostics-mcp
3
+ Version: 0.5.0
4
+ Summary: FastMCP server exposing macOS diagnostic scripts as MCP tools
5
+ Author: Thomas Juul Dyhr
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/docdyhr/mac-diagnostics
8
+ Project-URL: Changelog, https://github.com/docdyhr/mac-diagnostics/blob/main/CHANGELOG.md
9
+ Keywords: macos,mcp,diagnostics,fastmcp
10
+ Classifier: Environment :: MacOS X
11
+ Classifier: Operating System :: MacOS
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: System :: Monitoring
14
+ Requires-Python: >=3.11
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: fastmcp>=2.0
18
+ Provides-Extra: dev
19
+ Requires-Dist: pytest>=8.0; extra == "dev"
20
+ Requires-Dist: ruff>=0.4; extra == "dev"
21
+ Dynamic: license-file
22
+
23
+ # mac-diagnostics
24
+
25
+ ![CI](https://github.com/docdyhr/mac-diagnostics/actions/workflows/ci.yml/badge.svg)
26
+
27
+ Small macOS diagnostic shell scripts — sleep/wake, crashes, battery, disk,
28
+ network, security, backups, storage, and Wi-Fi — plus an MCP server that
29
+ exposes them to AI agents (Claude Desktop, Claude Code, Cursor, VS Code, and
30
+ others).
31
+
32
+ ## Scripts
33
+
34
+ All scripts live in `mac_diagnostics_mcp/scripts/` and run standalone — no
35
+ Python required:
36
+
37
+ - `mac-sleep-investigate.sh` — investigate sleep blockers, wake reasons, dark wakes, login/logout events, and likely always-awake processes.
38
+ - `mac-startup-items.sh` — inventory launch agents, launch daemons, login items, and common startup services.
39
+ - `mac-crashes.sh` — crash and hang trend analysis (per-app repeat offenders, kernel panics, JetsamEvent OOM kills, Microstackshots hang reports across modern .ips/.diag and legacy .crash formats), plus crash-related unified log entries and watchdog kills.
40
+ - `mac-battery.sh` — inspect battery health, cycle count, charging state, thermal state, and recent charging events.
41
+ - `mac-cpu-memory.sh` — inspect CPU usage, memory pressure, swap usage, thermal throttling, and related log events.
42
+ - `mac-disk-health.sh` — inspect free space, disk details, SMART status, storage profiler data, large home directories, and Time Machine state.
43
+ - `mac-network.sh` — inspect network services, interfaces, routes, DNS, connectivity, Wi-Fi state, established connections, listening ports, and HTTP latency.
44
+ - `mac-quick-health.sh` — fast overview across CPU, memory, disk, network, sleep blockers, battery, crashes, startup items, and thermal state.
45
+ - `mac-security.sh` — baseline security audit: FileVault, SIP, Gatekeeper, XProtect, application firewall, sharing services via listening ports, account hygiene, and a code-signing spot-check of third-party persistence items.
46
+ - `mac-backup.sh` — Time Machine health: destination configured, last-backup age, running state, local snapshot usage.
47
+ - `mac-storage.sh` — storage breakdown: overall usage, purgeable space, and the size of the usual heavyweight directories (Xcode DerivedData, simulators, Docker, caches, iOS backups, Downloads).
48
+ - `mac-wifi.sh` — Wi-Fi link quality: power, association, RSSI, noise, SNR, channel, and transmit rate.
49
+ - `mac-software-update.sh` — software-update status: pending macOS updates, automatic-update settings, XProtect definition age, and last successful update check.
50
+
51
+ **Developer environment tooling:**
52
+
53
+ - `mac-mcp-servers.sh` — audit MCP server configs across AI clients: deep audit of Claude Desktop (type classification, path health checks, env var key names with values redacted) plus detection of Claude Code, Cursor, VS Code, and Windsurf configs.
54
+ - `mac-node-packages.sh` — audit Node.js and Bun ecosystem: detect all Node installations, list npm global packages per prefix, show Bun tools in `~/.bun/bin`, and report available updates.
55
+ - `mac-node-update.sh` — show or apply updates for global npm and Bun packages; with `--include-mcp-venvs` also audits/upgrades pip packages in Python venv MCP servers.
56
+
57
+ ### Machine-readable findings
58
+
59
+ Every report ends with a `Machine-readable findings` section of one-line
60
+ findings:
61
+
62
+ ```
63
+ FINDING:WARN:disk: boot volume / is 92% full
64
+ FINDING:CRIT:network: no outbound connectivity (ping 1.1.1.1 failed) [suggest: investigate_network]
65
+ ```
66
+
67
+ Severity is `INFO` / `WARN` / `CRIT`. The MCP server lifts these into
68
+ structured tool output, so an agent can react to them deterministically
69
+ instead of parsing the prose report. A finding may end with an
70
+ **escalation hint** — `[suggest: tool(args)]` — which the server exposes as
71
+ a structured `suggestion` field naming the recommended follow-up tool.
72
+
73
+ ### Conditional-depth checks
74
+
75
+ The expensive unified-log (`log show`) checks in `mac-sleep-investigate.sh`,
76
+ `mac-crashes.sh`, and `mac-cpu-memory.sh` run only when a cheap trigger
77
+ fires (active sleep blocker, crash reports on disk, memory pressure,
78
+ throttling) or `--deep` is passed. Skipped checks are listed as
79
+ `SKIPPED: <check> (no trigger; use --deep to force)` in the report — a
80
+ clean machine's crash report takes well under a second. The MCP tools
81
+ expose this as `deep: false` by default.
82
+
83
+ ## MCP server
84
+
85
+ ### Install
86
+
87
+ From a clone (development):
88
+
89
+ ```bash
90
+ python -m pip install -e .
91
+ mac-diagnostics-mcp # runs the server on stdio
92
+ ```
93
+
94
+ Or with zero install, straight from PyPI (once published):
95
+
96
+ ```bash
97
+ uvx mac-diagnostics-mcp
98
+ ```
99
+
100
+ ### Configure your client
101
+
102
+ **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:
103
+
104
+ ```json
105
+ {
106
+ "mcpServers": {
107
+ "mac-diagnostics": {
108
+ "command": "uvx",
109
+ "args": ["mac-diagnostics-mcp"]
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ **Claude Code** — `~/.claude.json` (same `mcpServers` shape), or:
116
+
117
+ ```bash
118
+ claude mcp add mac-diagnostics -- uvx mac-diagnostics-mcp
119
+ ```
120
+
121
+ **Cursor** — `~/.cursor/mcp.json` (same `mcpServers` shape as Claude Desktop).
122
+
123
+ **VS Code** — `~/Library/Application Support/Code/User/mcp.json` (same shape).
124
+
125
+ For a development checkout, point the client at the console script inside the
126
+ venv instead:
127
+
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "mac-diagnostics": {
132
+ "command": "/path/to/mac-diagnostics/.venv/bin/mac-diagnostics-mcp"
133
+ }
134
+ }
135
+ }
136
+ ```
137
+
138
+ ### Tools
139
+
140
+ The server exposes 17 tools. Each returns a structured result:
141
+ `status` (`ok` / `info` / `warn` / `crit`), a machine-readable `findings`
142
+ list, and the full prose `report`. Check `findings` first; read the report
143
+ only for detail.
144
+
145
+ Every read-only tool also accepts `compare_last: true`, which diffs the
146
+ findings against the previous run with the same parameters and adds a
147
+ `delta` key (`new` / `resolved` / `changed` / `status_change`). Run history
148
+ lives in `~/.local/state/mac-diagnostics/`; see
149
+ [docs/baselines-design.md](docs/baselines-design.md).
150
+
151
+ | Tool | Description | Mutates? |
152
+ |---|---|---|
153
+ | `triage` | Map a symptom in plain language to an ordered tool plan | no |
154
+ | `quick_health_check` | Fast 30-second overview | no |
155
+ | `investigate_sleep` | Sleep blockers, wake reasons | no |
156
+ | `investigate_cpu_memory` | CPU usage, memory pressure | no |
157
+ | `investigate_disk` | SMART status, free space | no |
158
+ | `investigate_network` | Connectivity, DNS, routing | no |
159
+ | `investigate_crashes` | App crash/hang trends, panics, OOM kills | no |
160
+ | `investigate_battery` | Battery health, cycle count | no |
161
+ | `investigate_startup_items` | Launch agents and daemons, with code-signing assessment | no |
162
+ | `security_audit` | FileVault, SIP, firewall, sharing, persistence spot-check | no |
163
+ | `backup_audit` | Time Machine destination, last-backup age, snapshots | no |
164
+ | `storage_breakdown` | What is consuming the boot volume | no |
165
+ | `wifi_quality` | Wi-Fi RSSI, noise, SNR, channel, Tx rate | no |
166
+ | `check_software_updates` | Pending macOS updates, auto-update settings, XProtect age | no |
167
+ | `list_mcp_servers` | Audit MCP configs across AI clients | no |
168
+ | `inspect_node_packages` | Node/Bun ecosystem audit and update report | no |
169
+ | `update_node_packages` | Apply npm/bun updates (dry-run by default) | **only with `apply=true`** |
170
+
171
+ All read-only tools carry `readOnlyHint` annotations so clients can
172
+ auto-approve them safely.
173
+
174
+ ### Mutation guard
175
+
176
+ `update_node_packages(apply=true)` modifies the system (`brew upgrade`,
177
+ `npm update -g`, `pip install --upgrade`). It is refused unless the server
178
+ was started with:
179
+
180
+ ```json
181
+ {
182
+ "mcpServers": {
183
+ "mac-diagnostics": {
184
+ "command": "uvx",
185
+ "args": ["mac-diagnostics-mcp"],
186
+ "env": { "MAC_DIAG_ALLOW_MUTATIONS": "1" }
187
+ }
188
+ }
189
+ }
190
+ ```
191
+
192
+ Without it, the tool returns a structured refusal — a prompt-injected or
193
+ over-eager agent cannot run upgrades.
194
+
195
+ ## Example prompts
196
+
197
+ With the MCP server configured, ask your agent:
198
+
199
+ **System overview**
200
+ - "Run a quick health check on my Mac."
201
+
202
+ **Sleep & wake**
203
+ - "Investigate why my Mac isn't sleeping."
204
+ - "Check for sleep issues from the last 48 hours." *(uses `since` param)*
205
+
206
+ **CPU & memory**
207
+ - "Diagnose high CPU and memory pressure."
208
+ - "Check CPU and memory from the last 2 hours." *(uses `since` param)*
209
+
210
+ **Disk**
211
+ - "Check my disk health and free space."
212
+ - "Show verbose disk info including all partitions." *(uses `verbose` param)*
213
+
214
+ **Network**
215
+ - "Test my network connectivity and DNS."
216
+
217
+ **Crashes**
218
+ - "Show recent app crashes and panics."
219
+ - "List crashes from the last 48 hours." *(uses `since` param)*
220
+
221
+ **Battery** *(MacBook only)*
222
+ - "Check my battery health and cycle count."
223
+
224
+ **Startup items**
225
+ - "List everything that launches at startup."
226
+
227
+ **Security**
228
+ - "Run a security audit of this Mac."
229
+ - "Are any of my startup items unsigned?"
230
+
231
+ **Backups**
232
+ - "When did my last Time Machine backup finish?"
233
+
234
+ **Storage**
235
+ - "My disk is full — what is taking up the space?"
236
+
237
+ **Wi-Fi**
238
+ - "Is my Wi-Fi signal any good?"
239
+
240
+ **Software updates**
241
+ - "Are my macOS updates up to date?"
242
+
243
+ **Symptoms → plan**
244
+ - "My battery drains overnight — what should we check?" *(uses `triage`)*
245
+
246
+ **Change since last time**
247
+ - "Run the health check and tell me what changed since last week." *(uses `compare_last`)*
248
+
249
+ **Workflow prompts** — the server also ships guided multi-tool workflows:
250
+ `diagnose_slow_mac`, `investigate_sleep_issues`, `weekly_maintenance`,
251
+ `security_review`, and `pre_travel_check`.
252
+
253
+ **MCP server audit**
254
+ - "Audit my MCP server configuration across all AI clients."
255
+
256
+ **Node / Bun packages**
257
+ - "Audit my MCP server configuration across all AI clients."
258
+
259
+ **Node / Bun packages**
260
+ - "Audit my Node.js and Bun global packages."
261
+ - "Check for npm and Bun package updates (dry-run)."
262
+ - "Apply npm and Bun updates, including Python MCP venvs." *(uses `apply` + `include_mcp_venvs` params; requires the mutation guard)*
263
+
264
+ ## Usage (standalone scripts)
265
+
266
+ Run a script directly:
267
+
268
+ ```bash
269
+ ./mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh --since 24h
270
+ ./mac_diagnostics_mcp/scripts/mac-quick-health.sh
271
+ ./mac_diagnostics_mcp/scripts/mac-startup-items.sh
272
+ ./mac_diagnostics_mcp/scripts/mac-crashes.sh --since 48h
273
+ ./mac_diagnostics_mcp/scripts/mac-battery.sh
274
+ ./mac_diagnostics_mcp/scripts/mac-cpu-memory.sh --since 2h
275
+ ./mac_diagnostics_mcp/scripts/mac-disk-health.sh
276
+ ./mac_diagnostics_mcp/scripts/mac-network.sh
277
+ ./mac_diagnostics_mcp/scripts/mac-security.sh
278
+ ./mac_diagnostics_mcp/scripts/mac-backup.sh
279
+ ./mac_diagnostics_mcp/scripts/mac-storage.sh
280
+ ./mac_diagnostics_mcp/scripts/mac-wifi.sh
281
+ ./mac_diagnostics_mcp/scripts/mac-software-update.sh
282
+
283
+ # Developer environment tools
284
+ ./mac_diagnostics_mcp/scripts/mac-mcp-servers.sh --stdout
285
+ ./mac_diagnostics_mcp/scripts/mac-node-packages.sh --stdout
286
+ ./mac_diagnostics_mcp/scripts/mac-node-update.sh --stdout # dry-run
287
+ ./mac_diagnostics_mcp/scripts/mac-node-update.sh --stdout --apply # apply updates
288
+ ./mac_diagnostics_mcp/scripts/mac-node-update.sh --stdout --apply --include-mcp-venvs
289
+ ```
290
+
291
+ By default, each script writes a timestamped report folder on your Desktop.
292
+ With `--stdout` (the mode the MCP server uses), the report goes to a temp dir
293
+ instead — agents calling tools repeatedly will not clutter your Desktop.
294
+
295
+ Use `--out` to choose a report folder explicitly:
296
+
297
+ ```bash
298
+ ./mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh --since 24h --out ~/Desktop/sleep-report
299
+ ```
300
+
301
+ ## Requirements
302
+
303
+ - macOS
304
+ - Bash
305
+ - GNU `timeout` available as `timeout` in `PATH` (for example via Homebrew `coreutils`)
306
+ - Standard macOS tools used by the scripts, such as `pmset`, `log`, `launchctl`, `system_profiler`, `ioreg`, and `osascript`
307
+ - Python ≥ 3.11 and `fastmcp` for the MCP server only
308
+
309
+ Some commands may require additional macOS permissions or may return partial output depending on privacy settings and whether they are run with elevated privileges.
310
+
311
+ ## Development checks
312
+
313
+ ```bash
314
+ bash -n mac_diagnostics_mcp/scripts/*.sh
315
+ shellcheck --shell=bash mac_diagnostics_mcp/scripts/*.sh
316
+ ruff check mac_diagnostics_mcp/ tests/
317
+ pytest
318
+ ```
319
+
320
+ ## Privacy note
321
+
322
+ Generated reports can include hostnames, usernames, process names, launch agents, installed services, device/power state, and excerpts from macOS logs. Review report output before sharing it outside your machine.
@@ -0,0 +1,300 @@
1
+ # mac-diagnostics
2
+
3
+ ![CI](https://github.com/docdyhr/mac-diagnostics/actions/workflows/ci.yml/badge.svg)
4
+
5
+ Small macOS diagnostic shell scripts — sleep/wake, crashes, battery, disk,
6
+ network, security, backups, storage, and Wi-Fi — plus an MCP server that
7
+ exposes them to AI agents (Claude Desktop, Claude Code, Cursor, VS Code, and
8
+ others).
9
+
10
+ ## Scripts
11
+
12
+ All scripts live in `mac_diagnostics_mcp/scripts/` and run standalone — no
13
+ Python required:
14
+
15
+ - `mac-sleep-investigate.sh` — investigate sleep blockers, wake reasons, dark wakes, login/logout events, and likely always-awake processes.
16
+ - `mac-startup-items.sh` — inventory launch agents, launch daemons, login items, and common startup services.
17
+ - `mac-crashes.sh` — crash and hang trend analysis (per-app repeat offenders, kernel panics, JetsamEvent OOM kills, Microstackshots hang reports across modern .ips/.diag and legacy .crash formats), plus crash-related unified log entries and watchdog kills.
18
+ - `mac-battery.sh` — inspect battery health, cycle count, charging state, thermal state, and recent charging events.
19
+ - `mac-cpu-memory.sh` — inspect CPU usage, memory pressure, swap usage, thermal throttling, and related log events.
20
+ - `mac-disk-health.sh` — inspect free space, disk details, SMART status, storage profiler data, large home directories, and Time Machine state.
21
+ - `mac-network.sh` — inspect network services, interfaces, routes, DNS, connectivity, Wi-Fi state, established connections, listening ports, and HTTP latency.
22
+ - `mac-quick-health.sh` — fast overview across CPU, memory, disk, network, sleep blockers, battery, crashes, startup items, and thermal state.
23
+ - `mac-security.sh` — baseline security audit: FileVault, SIP, Gatekeeper, XProtect, application firewall, sharing services via listening ports, account hygiene, and a code-signing spot-check of third-party persistence items.
24
+ - `mac-backup.sh` — Time Machine health: destination configured, last-backup age, running state, local snapshot usage.
25
+ - `mac-storage.sh` — storage breakdown: overall usage, purgeable space, and the size of the usual heavyweight directories (Xcode DerivedData, simulators, Docker, caches, iOS backups, Downloads).
26
+ - `mac-wifi.sh` — Wi-Fi link quality: power, association, RSSI, noise, SNR, channel, and transmit rate.
27
+ - `mac-software-update.sh` — software-update status: pending macOS updates, automatic-update settings, XProtect definition age, and last successful update check.
28
+
29
+ **Developer environment tooling:**
30
+
31
+ - `mac-mcp-servers.sh` — audit MCP server configs across AI clients: deep audit of Claude Desktop (type classification, path health checks, env var key names with values redacted) plus detection of Claude Code, Cursor, VS Code, and Windsurf configs.
32
+ - `mac-node-packages.sh` — audit Node.js and Bun ecosystem: detect all Node installations, list npm global packages per prefix, show Bun tools in `~/.bun/bin`, and report available updates.
33
+ - `mac-node-update.sh` — show or apply updates for global npm and Bun packages; with `--include-mcp-venvs` also audits/upgrades pip packages in Python venv MCP servers.
34
+
35
+ ### Machine-readable findings
36
+
37
+ Every report ends with a `Machine-readable findings` section of one-line
38
+ findings:
39
+
40
+ ```
41
+ FINDING:WARN:disk: boot volume / is 92% full
42
+ FINDING:CRIT:network: no outbound connectivity (ping 1.1.1.1 failed) [suggest: investigate_network]
43
+ ```
44
+
45
+ Severity is `INFO` / `WARN` / `CRIT`. The MCP server lifts these into
46
+ structured tool output, so an agent can react to them deterministically
47
+ instead of parsing the prose report. A finding may end with an
48
+ **escalation hint** — `[suggest: tool(args)]` — which the server exposes as
49
+ a structured `suggestion` field naming the recommended follow-up tool.
50
+
51
+ ### Conditional-depth checks
52
+
53
+ The expensive unified-log (`log show`) checks in `mac-sleep-investigate.sh`,
54
+ `mac-crashes.sh`, and `mac-cpu-memory.sh` run only when a cheap trigger
55
+ fires (active sleep blocker, crash reports on disk, memory pressure,
56
+ throttling) or `--deep` is passed. Skipped checks are listed as
57
+ `SKIPPED: <check> (no trigger; use --deep to force)` in the report — a
58
+ clean machine's crash report takes well under a second. The MCP tools
59
+ expose this as `deep: false` by default.
60
+
61
+ ## MCP server
62
+
63
+ ### Install
64
+
65
+ From a clone (development):
66
+
67
+ ```bash
68
+ python -m pip install -e .
69
+ mac-diagnostics-mcp # runs the server on stdio
70
+ ```
71
+
72
+ Or with zero install, straight from PyPI (once published):
73
+
74
+ ```bash
75
+ uvx mac-diagnostics-mcp
76
+ ```
77
+
78
+ ### Configure your client
79
+
80
+ **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:
81
+
82
+ ```json
83
+ {
84
+ "mcpServers": {
85
+ "mac-diagnostics": {
86
+ "command": "uvx",
87
+ "args": ["mac-diagnostics-mcp"]
88
+ }
89
+ }
90
+ }
91
+ ```
92
+
93
+ **Claude Code** — `~/.claude.json` (same `mcpServers` shape), or:
94
+
95
+ ```bash
96
+ claude mcp add mac-diagnostics -- uvx mac-diagnostics-mcp
97
+ ```
98
+
99
+ **Cursor** — `~/.cursor/mcp.json` (same `mcpServers` shape as Claude Desktop).
100
+
101
+ **VS Code** — `~/Library/Application Support/Code/User/mcp.json` (same shape).
102
+
103
+ For a development checkout, point the client at the console script inside the
104
+ venv instead:
105
+
106
+ ```json
107
+ {
108
+ "mcpServers": {
109
+ "mac-diagnostics": {
110
+ "command": "/path/to/mac-diagnostics/.venv/bin/mac-diagnostics-mcp"
111
+ }
112
+ }
113
+ }
114
+ ```
115
+
116
+ ### Tools
117
+
118
+ The server exposes 17 tools. Each returns a structured result:
119
+ `status` (`ok` / `info` / `warn` / `crit`), a machine-readable `findings`
120
+ list, and the full prose `report`. Check `findings` first; read the report
121
+ only for detail.
122
+
123
+ Every read-only tool also accepts `compare_last: true`, which diffs the
124
+ findings against the previous run with the same parameters and adds a
125
+ `delta` key (`new` / `resolved` / `changed` / `status_change`). Run history
126
+ lives in `~/.local/state/mac-diagnostics/`; see
127
+ [docs/baselines-design.md](docs/baselines-design.md).
128
+
129
+ | Tool | Description | Mutates? |
130
+ |---|---|---|
131
+ | `triage` | Map a symptom in plain language to an ordered tool plan | no |
132
+ | `quick_health_check` | Fast 30-second overview | no |
133
+ | `investigate_sleep` | Sleep blockers, wake reasons | no |
134
+ | `investigate_cpu_memory` | CPU usage, memory pressure | no |
135
+ | `investigate_disk` | SMART status, free space | no |
136
+ | `investigate_network` | Connectivity, DNS, routing | no |
137
+ | `investigate_crashes` | App crash/hang trends, panics, OOM kills | no |
138
+ | `investigate_battery` | Battery health, cycle count | no |
139
+ | `investigate_startup_items` | Launch agents and daemons, with code-signing assessment | no |
140
+ | `security_audit` | FileVault, SIP, firewall, sharing, persistence spot-check | no |
141
+ | `backup_audit` | Time Machine destination, last-backup age, snapshots | no |
142
+ | `storage_breakdown` | What is consuming the boot volume | no |
143
+ | `wifi_quality` | Wi-Fi RSSI, noise, SNR, channel, Tx rate | no |
144
+ | `check_software_updates` | Pending macOS updates, auto-update settings, XProtect age | no |
145
+ | `list_mcp_servers` | Audit MCP configs across AI clients | no |
146
+ | `inspect_node_packages` | Node/Bun ecosystem audit and update report | no |
147
+ | `update_node_packages` | Apply npm/bun updates (dry-run by default) | **only with `apply=true`** |
148
+
149
+ All read-only tools carry `readOnlyHint` annotations so clients can
150
+ auto-approve them safely.
151
+
152
+ ### Mutation guard
153
+
154
+ `update_node_packages(apply=true)` modifies the system (`brew upgrade`,
155
+ `npm update -g`, `pip install --upgrade`). It is refused unless the server
156
+ was started with:
157
+
158
+ ```json
159
+ {
160
+ "mcpServers": {
161
+ "mac-diagnostics": {
162
+ "command": "uvx",
163
+ "args": ["mac-diagnostics-mcp"],
164
+ "env": { "MAC_DIAG_ALLOW_MUTATIONS": "1" }
165
+ }
166
+ }
167
+ }
168
+ ```
169
+
170
+ Without it, the tool returns a structured refusal — a prompt-injected or
171
+ over-eager agent cannot run upgrades.
172
+
173
+ ## Example prompts
174
+
175
+ With the MCP server configured, ask your agent:
176
+
177
+ **System overview**
178
+ - "Run a quick health check on my Mac."
179
+
180
+ **Sleep & wake**
181
+ - "Investigate why my Mac isn't sleeping."
182
+ - "Check for sleep issues from the last 48 hours." *(uses `since` param)*
183
+
184
+ **CPU & memory**
185
+ - "Diagnose high CPU and memory pressure."
186
+ - "Check CPU and memory from the last 2 hours." *(uses `since` param)*
187
+
188
+ **Disk**
189
+ - "Check my disk health and free space."
190
+ - "Show verbose disk info including all partitions." *(uses `verbose` param)*
191
+
192
+ **Network**
193
+ - "Test my network connectivity and DNS."
194
+
195
+ **Crashes**
196
+ - "Show recent app crashes and panics."
197
+ - "List crashes from the last 48 hours." *(uses `since` param)*
198
+
199
+ **Battery** *(MacBook only)*
200
+ - "Check my battery health and cycle count."
201
+
202
+ **Startup items**
203
+ - "List everything that launches at startup."
204
+
205
+ **Security**
206
+ - "Run a security audit of this Mac."
207
+ - "Are any of my startup items unsigned?"
208
+
209
+ **Backups**
210
+ - "When did my last Time Machine backup finish?"
211
+
212
+ **Storage**
213
+ - "My disk is full — what is taking up the space?"
214
+
215
+ **Wi-Fi**
216
+ - "Is my Wi-Fi signal any good?"
217
+
218
+ **Software updates**
219
+ - "Are my macOS updates up to date?"
220
+
221
+ **Symptoms → plan**
222
+ - "My battery drains overnight — what should we check?" *(uses `triage`)*
223
+
224
+ **Change since last time**
225
+ - "Run the health check and tell me what changed since last week." *(uses `compare_last`)*
226
+
227
+ **Workflow prompts** — the server also ships guided multi-tool workflows:
228
+ `diagnose_slow_mac`, `investigate_sleep_issues`, `weekly_maintenance`,
229
+ `security_review`, and `pre_travel_check`.
230
+
231
+ **MCP server audit**
232
+ - "Audit my MCP server configuration across all AI clients."
233
+
234
+ **Node / Bun packages**
235
+ - "Audit my MCP server configuration across all AI clients."
236
+
237
+ **Node / Bun packages**
238
+ - "Audit my Node.js and Bun global packages."
239
+ - "Check for npm and Bun package updates (dry-run)."
240
+ - "Apply npm and Bun updates, including Python MCP venvs." *(uses `apply` + `include_mcp_venvs` params; requires the mutation guard)*
241
+
242
+ ## Usage (standalone scripts)
243
+
244
+ Run a script directly:
245
+
246
+ ```bash
247
+ ./mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh --since 24h
248
+ ./mac_diagnostics_mcp/scripts/mac-quick-health.sh
249
+ ./mac_diagnostics_mcp/scripts/mac-startup-items.sh
250
+ ./mac_diagnostics_mcp/scripts/mac-crashes.sh --since 48h
251
+ ./mac_diagnostics_mcp/scripts/mac-battery.sh
252
+ ./mac_diagnostics_mcp/scripts/mac-cpu-memory.sh --since 2h
253
+ ./mac_diagnostics_mcp/scripts/mac-disk-health.sh
254
+ ./mac_diagnostics_mcp/scripts/mac-network.sh
255
+ ./mac_diagnostics_mcp/scripts/mac-security.sh
256
+ ./mac_diagnostics_mcp/scripts/mac-backup.sh
257
+ ./mac_diagnostics_mcp/scripts/mac-storage.sh
258
+ ./mac_diagnostics_mcp/scripts/mac-wifi.sh
259
+ ./mac_diagnostics_mcp/scripts/mac-software-update.sh
260
+
261
+ # Developer environment tools
262
+ ./mac_diagnostics_mcp/scripts/mac-mcp-servers.sh --stdout
263
+ ./mac_diagnostics_mcp/scripts/mac-node-packages.sh --stdout
264
+ ./mac_diagnostics_mcp/scripts/mac-node-update.sh --stdout # dry-run
265
+ ./mac_diagnostics_mcp/scripts/mac-node-update.sh --stdout --apply # apply updates
266
+ ./mac_diagnostics_mcp/scripts/mac-node-update.sh --stdout --apply --include-mcp-venvs
267
+ ```
268
+
269
+ By default, each script writes a timestamped report folder on your Desktop.
270
+ With `--stdout` (the mode the MCP server uses), the report goes to a temp dir
271
+ instead — agents calling tools repeatedly will not clutter your Desktop.
272
+
273
+ Use `--out` to choose a report folder explicitly:
274
+
275
+ ```bash
276
+ ./mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh --since 24h --out ~/Desktop/sleep-report
277
+ ```
278
+
279
+ ## Requirements
280
+
281
+ - macOS
282
+ - Bash
283
+ - GNU `timeout` available as `timeout` in `PATH` (for example via Homebrew `coreutils`)
284
+ - Standard macOS tools used by the scripts, such as `pmset`, `log`, `launchctl`, `system_profiler`, `ioreg`, and `osascript`
285
+ - Python ≥ 3.11 and `fastmcp` for the MCP server only
286
+
287
+ Some commands may require additional macOS permissions or may return partial output depending on privacy settings and whether they are run with elevated privileges.
288
+
289
+ ## Development checks
290
+
291
+ ```bash
292
+ bash -n mac_diagnostics_mcp/scripts/*.sh
293
+ shellcheck --shell=bash mac_diagnostics_mcp/scripts/*.sh
294
+ ruff check mac_diagnostics_mcp/ tests/
295
+ pytest
296
+ ```
297
+
298
+ ## Privacy note
299
+
300
+ Generated reports can include hostnames, usernames, process names, launch agents, installed services, device/power state, and excerpts from macOS logs. Review report output before sharing it outside your machine.