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.
- mac_diagnostics_mcp-0.5.0/LICENSE +21 -0
- mac_diagnostics_mcp-0.5.0/PKG-INFO +322 -0
- mac_diagnostics_mcp-0.5.0/README.md +300 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/__init__.py +0 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/runner.py +129 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/lib-assess.sh +68 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/lib-findings.sh +59 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-backup.sh +210 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-battery.sh +203 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-cpu-memory.sh +265 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-crashes.sh +399 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-disk-health.sh +227 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-mcp-servers.sh +452 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-network.sh +218 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-node-packages.sh +272 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-node-update.sh +328 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-quick-health.sh +216 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-security.sh +291 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh +305 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-software-update.sh +241 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-startup-items.sh +238 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-storage.sh +215 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/scripts/mac-wifi.sh +204 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/server.py +456 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/state.py +150 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp/triage.py +182 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/PKG-INFO +322 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/SOURCES.txt +34 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/dependency_links.txt +1 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/entry_points.txt +2 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/requires.txt +5 -0
- mac_diagnostics_mcp-0.5.0/mac_diagnostics_mcp.egg-info/top_level.txt +1 -0
- mac_diagnostics_mcp-0.5.0/pyproject.toml +54 -0
- mac_diagnostics_mcp-0.5.0/setup.cfg +4 -0
- mac_diagnostics_mcp-0.5.0/tests/test_runner.py +446 -0
- 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
|
+

|
|
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
|
+

|
|
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.
|
|
File without changes
|