mac-diagnostics-mcp 0.5.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.
Files changed (29) hide show
  1. mac_diagnostics_mcp/__init__.py +0 -0
  2. mac_diagnostics_mcp/runner.py +129 -0
  3. mac_diagnostics_mcp/scripts/lib-assess.sh +68 -0
  4. mac_diagnostics_mcp/scripts/lib-findings.sh +59 -0
  5. mac_diagnostics_mcp/scripts/mac-backup.sh +210 -0
  6. mac_diagnostics_mcp/scripts/mac-battery.sh +203 -0
  7. mac_diagnostics_mcp/scripts/mac-cpu-memory.sh +265 -0
  8. mac_diagnostics_mcp/scripts/mac-crashes.sh +399 -0
  9. mac_diagnostics_mcp/scripts/mac-disk-health.sh +227 -0
  10. mac_diagnostics_mcp/scripts/mac-mcp-servers.sh +452 -0
  11. mac_diagnostics_mcp/scripts/mac-network.sh +218 -0
  12. mac_diagnostics_mcp/scripts/mac-node-packages.sh +272 -0
  13. mac_diagnostics_mcp/scripts/mac-node-update.sh +328 -0
  14. mac_diagnostics_mcp/scripts/mac-quick-health.sh +216 -0
  15. mac_diagnostics_mcp/scripts/mac-security.sh +291 -0
  16. mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh +305 -0
  17. mac_diagnostics_mcp/scripts/mac-software-update.sh +241 -0
  18. mac_diagnostics_mcp/scripts/mac-startup-items.sh +238 -0
  19. mac_diagnostics_mcp/scripts/mac-storage.sh +215 -0
  20. mac_diagnostics_mcp/scripts/mac-wifi.sh +204 -0
  21. mac_diagnostics_mcp/server.py +456 -0
  22. mac_diagnostics_mcp/state.py +150 -0
  23. mac_diagnostics_mcp/triage.py +182 -0
  24. mac_diagnostics_mcp-0.5.0.dist-info/METADATA +322 -0
  25. mac_diagnostics_mcp-0.5.0.dist-info/RECORD +29 -0
  26. mac_diagnostics_mcp-0.5.0.dist-info/WHEEL +5 -0
  27. mac_diagnostics_mcp-0.5.0.dist-info/entry_points.txt +2 -0
  28. mac_diagnostics_mcp-0.5.0.dist-info/licenses/LICENSE +21 -0
  29. mac_diagnostics_mcp-0.5.0.dist-info/top_level.txt +1 -0
File without changes
@@ -0,0 +1,129 @@
1
+ import re
2
+ import subprocess
3
+ from pathlib import Path
4
+
5
+ from mac_diagnostics_mcp import state
6
+
7
+ SCRIPTS_DIR = Path(__file__).parent / "scripts"
8
+ MAX_OUTPUT_BYTES = 500_000
9
+ # Well below the MCP client's ~240s call timeout, leaving margin for process
10
+ # teardown and the round trip back through the client.
11
+ SCRIPT_TIMEOUT_SECS = 90
12
+
13
+ # Scripts emit machine-readable lines via scripts/lib-findings.sh:
14
+ # FINDING:<SEVERITY>:<domain>: <free-text message> [suggest: <tool>(<args>)]
15
+ # The trailing "[suggest: ...]" is an optional escalation hint pointing at the
16
+ # next tool to run; it is lifted into a structured "suggestion" field.
17
+ FINDING_RE = re.compile(
18
+ r"^FINDING:(INFO|WARN|CRIT):([a-z0-9-]+): (.+?)(?:\s\[suggest: ([^\]]*)\])?$",
19
+ re.MULTILINE,
20
+ )
21
+
22
+ _SEVERITY_RANK = {"INFO": 0, "WARN": 1, "CRIT": 2}
23
+
24
+
25
+ def extract_findings(output: str) -> list[dict[str, str]]:
26
+ """Pull machine-readable FINDING: lines out of a report.
27
+
28
+ A finding carries severity / domain / detail, plus an optional
29
+ "suggestion" key naming the follow-up MCP tool the script recommends
30
+ (e.g. "investigate_disk(verbose=true)"). Suggestions are hints, not
31
+ obligations — the agent decides whether to follow them.
32
+ """
33
+ findings = []
34
+ for m in FINDING_RE.finditer(output):
35
+ finding = {
36
+ "severity": m.group(1),
37
+ "domain": m.group(2),
38
+ "detail": m.group(3).strip(),
39
+ }
40
+ suggestion = (m.group(4) or "").strip()
41
+ if suggestion:
42
+ finding["suggestion"] = suggestion
43
+ findings.append(finding)
44
+ return findings
45
+
46
+
47
+ def worst_severity(findings: list[dict[str, str]]) -> str:
48
+ """Overall status for a set of findings: ok / info / warn / crit."""
49
+ if not findings:
50
+ return "ok"
51
+ worst = max(_SEVERITY_RANK[f["severity"]] for f in findings)
52
+ return {0: "info", 1: "warn", 2: "crit"}[worst]
53
+
54
+
55
+ def run_diagnostic(script_name: str, **kwargs) -> str:
56
+ script = SCRIPTS_DIR / script_name
57
+ if not script.exists():
58
+ raise FileNotFoundError(f"Script not found: {script}")
59
+
60
+ cmd = [str(script), "--stdout"]
61
+ for k, v in kwargs.items():
62
+ if v is None or v is False:
63
+ continue
64
+ flag = f"--{k.replace('_', '-')}"
65
+ if v is True:
66
+ cmd.append(flag)
67
+ else:
68
+ cmd.extend([flag, str(v)])
69
+
70
+ proc = subprocess.Popen(
71
+ cmd,
72
+ stdout=subprocess.PIPE,
73
+ stderr=subprocess.PIPE,
74
+ text=True,
75
+ )
76
+ try:
77
+ out, err = proc.communicate(timeout=SCRIPT_TIMEOUT_SECS)
78
+ except subprocess.TimeoutExpired:
79
+ proc.kill()
80
+ try:
81
+ out, _ = proc.communicate(timeout=10)
82
+ except subprocess.TimeoutExpired:
83
+ out = ""
84
+ return (
85
+ out or ""
86
+ ) + f"\n[TIMED OUT after {SCRIPT_TIMEOUT_SECS}s — partial report above]"
87
+
88
+ if proc.returncode != 0:
89
+ raise RuntimeError(f"Script exited with code {proc.returncode}:\n{err.strip()}")
90
+
91
+ encoded = out.encode("utf-8", errors="replace")
92
+ if len(encoded) > MAX_OUTPUT_BYTES:
93
+ out = encoded[:MAX_OUTPUT_BYTES].decode("utf-8", errors="replace")
94
+ out += "\n[OUTPUT TRUNCATED AT 500KB]"
95
+
96
+ return out.strip()
97
+
98
+
99
+ def run_diagnostic_structured(script_name: str, **kwargs) -> dict:
100
+ """Run a diagnostic script and return structured output for agent consumers.
101
+
102
+ The full prose report is still included, but agents should look at
103
+ `findings` first: it is deterministic, small, and machine-readable,
104
+ whereas `report` is large and needs interpretation.
105
+
106
+ `compare_last=True` (popped here, never passed to the script) diffs the
107
+ findings against the previous run with identical parameters and adds a
108
+ `delta` key — see mac_diagnostics_mcp/state.py and
109
+ docs/baselines-design.md. Every run is recorded so a baseline always
110
+ exists for the next comparison.
111
+ """
112
+ compare_last = bool(kwargs.pop("compare_last", False))
113
+ report = run_diagnostic(script_name, **kwargs)
114
+ findings = extract_findings(report)
115
+ result = {
116
+ "script": script_name,
117
+ "status": worst_severity(findings),
118
+ "timed_out": "[TIMED OUT after" in report,
119
+ "truncated": "[OUTPUT TRUNCATED" in report,
120
+ "findings": findings,
121
+ "report": report,
122
+ }
123
+ params = dict(kwargs)
124
+ if compare_last:
125
+ delta = state.compute_delta(script_name, params, result["status"], findings)
126
+ if delta is not None:
127
+ result["delta"] = delta
128
+ state.record_run(script_name, params, result["status"], findings)
129
+ return result
@@ -0,0 +1,68 @@
1
+ #!/usr/bin/env bash
2
+ # lib-assess.sh — code-signing spot-check for third-party persistence items.
3
+ #
4
+ # Shared by mac-security.sh (always on) and mac-startup-items.sh (--assess).
5
+ # Can be sourced (defines assess_persistence_items) or executed directly so
6
+ # it works under `timeout` in a script's run() helper:
7
+ #
8
+ # run "Persistence items: code-signing spot-check" bash "$LIB_DIR/lib-assess.sh"
9
+ #
10
+ # Prints one normalized line per item:
11
+ # ITEM_STATUS|<plist name>|<program>|<status>
12
+ # status: SIGNED | UNSIGNED | MISSING | TEMP-PATH | SCRIPT | NO-PROGRAM
13
+ # (and ITEM_STATUS|(truncated)||CAPPED-AT-40 when the cap is hit).
14
+
15
+ assess_persistence_items() {
16
+ shopt -s nullglob
17
+ local seen="" count=0 plist name prog
18
+ for plist in ~/Library/LaunchAgents/*.plist \
19
+ /Library/LaunchAgents/*.plist \
20
+ /Library/LaunchDaemons/*.plist; do
21
+ name=$(basename "$plist")
22
+ case "$name" in com.apple.*) continue ;; esac
23
+ prog=$(/usr/libexec/PlistBuddy -c "Print :Program" "$plist" 2>/dev/null \
24
+ || /usr/libexec/PlistBuddy -c "Print :ProgramArguments:0" "$plist" 2>/dev/null \
25
+ || echo "")
26
+ if [[ -z "$prog" ]]; then
27
+ echo "ITEM_STATUS|$name||NO-PROGRAM"
28
+ continue
29
+ fi
30
+ case " $seen " in *" $prog "*) continue ;; esac
31
+ seen="$seen $prog"
32
+ count=$((count + 1))
33
+ if (( count > 40 )); then
34
+ echo "ITEM_STATUS|(truncated)||CAPPED-AT-40"
35
+ break
36
+ fi
37
+ if [[ ! -e "$prog" ]]; then
38
+ echo "ITEM_STATUS|$name|$prog|MISSING"
39
+ continue
40
+ fi
41
+ case "$prog" in
42
+ /tmp/*|/private/tmp/*|/var/folders/*|/private/var/folders/*)
43
+ echo "ITEM_STATUS|$name|$prog|TEMP-PATH"
44
+ continue
45
+ ;;
46
+ esac
47
+ # Scripts cannot be code-signed; being unsigned is expected for them.
48
+ case "$prog" in
49
+ *.sh|*.py|*.pl|*.rb|*.command)
50
+ echo "ITEM_STATUS|$name|$prog|SCRIPT"
51
+ continue
52
+ ;;
53
+ esac
54
+ if head -c 2 "$prog" 2>/dev/null | grep -q '^#!'; then
55
+ echo "ITEM_STATUS|$name|$prog|SCRIPT"
56
+ continue
57
+ fi
58
+ if codesign -v "$prog" 2>/dev/null; then
59
+ echo "ITEM_STATUS|$name|$prog|SIGNED"
60
+ else
61
+ echo "ITEM_STATUS|$name|$prog|UNSIGNED"
62
+ fi
63
+ done
64
+ }
65
+
66
+ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
67
+ assess_persistence_items
68
+ fi
@@ -0,0 +1,59 @@
1
+ #!/usr/bin/env bash
2
+ # lib-findings.sh — machine-readable findings for agent consumers.
3
+ #
4
+ # A finding is a single line in the report:
5
+ #
6
+ # FINDING:<SEVERITY>:<domain>: <free-text message> [suggest: <tool>(<args>)]
7
+ #
8
+ # SEVERITY: INFO (observation) | WARN (worth attention) | CRIT (act now).
9
+ # <domain> is a short lowercase tag like "disk", "memory", "sleep".
10
+ #
11
+ # The MCP server lifts these lines out of the report into structured tool
12
+ # output, so an agent can react to them deterministically instead of parsing
13
+ # the prose report. Keep messages on one line and free of colons at the start.
14
+ #
15
+ # Escalation hints: `finding --suggest "tool(args)" SEVERITY domain "msg"`
16
+ # appends "[suggest: tool(args)]" to the line. The MCP server lifts it into a
17
+ # structured "suggestion" field on the finding. A suggestion is a hint, never
18
+ # an obligation — the agent decides whether to follow it. Only reference
19
+ # registered MCP tools with valid parameters (tests/test_server.py enforces
20
+ # the tool names).
21
+
22
+ finding() {
23
+ local suggest=""
24
+ if [[ "${1:-}" == "--suggest" ]]; then
25
+ suggest="$2"
26
+ shift 2
27
+ fi
28
+ local severity="$1" domain="$2"
29
+ shift 2
30
+ if [[ -n "$suggest" ]]; then
31
+ echo "FINDING:${severity}:${domain}: $* [suggest: ${suggest}]"
32
+ else
33
+ echo "FINDING:${severity}:${domain}: $*"
34
+ fi
35
+ }
36
+
37
+ # Conditional-depth checks. Expensive checks (e.g. `log show`) should only run
38
+ # when a cheap trigger fired or the caller passed --deep. When a check is
39
+ # skipped, record it with skip_check and print_skipped_checks emits visible
40
+ # SKIPPED: lines in the report — skipping is never silent, and each line names
41
+ # the override so an agent can force the full run. The override flag defaults
42
+ # to --deep; a script may set SKIP_FORCE_HINT (e.g. "--assess") after sourcing.
43
+ SKIP_FORCE_HINT="${SKIP_FORCE_HINT:---deep}"
44
+ SKIPPED_CHECKS=()
45
+
46
+ skip_check() {
47
+ SKIPPED_CHECKS+=("$1")
48
+ echo "Skipped (no trigger; ${SKIP_FORCE_HINT} forces): $1" >&2
49
+ }
50
+
51
+ # Prints the skipped-checks section. Requires the script's section() helper.
52
+ print_skipped_checks() {
53
+ ((${#SKIPPED_CHECKS[@]} == 0)) && return 0
54
+ local c
55
+ section "Skipped checks (no trigger; re-run with ${SKIP_FORCE_HINT} to force)"
56
+ for c in "${SKIPPED_CHECKS[@]}"; do
57
+ echo "SKIPPED: $c (no trigger; use ${SKIP_FORCE_HINT} to force)"
58
+ done
59
+ }
@@ -0,0 +1,210 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ # shellcheck source=mac_diagnostics_mcp/scripts/lib-findings.sh
5
+ source "$(dirname "$0")/lib-findings.sh"
6
+
7
+ # mac-backup.sh — Time Machine health: destination, last-backup age,
8
+ # in-progress state, local snapshot usage.
9
+ #
10
+ # All checks are cheap (tmutil/defaults/diskutil, no log show). Every check
11
+ # emits a normalized KEY: value line; the findings block parses only those.
12
+
13
+ STDOUT_MODE=0
14
+ OUTDIR=""
15
+
16
+ usage() {
17
+ cat <<EOF
18
+ mac-backup.sh
19
+
20
+ Audit Time Machine backup health: destination configured, last successful
21
+ backup age, whether a backup is running, and local snapshot usage.
22
+
23
+ Usage:
24
+ $0 [options]
25
+
26
+ Options:
27
+ --out PATH Output folder
28
+ --stdout Print report to stdout when done (used by MCP server)
29
+ -h, --help Show help
30
+ EOF
31
+ }
32
+
33
+ while [[ $# -gt 0 ]]; do
34
+ case "$1" in
35
+ --out) OUTDIR="$2"; shift 2 ;;
36
+ --stdout) STDOUT_MODE=1; shift ;;
37
+ -h|--help) usage; exit 0 ;;
38
+ *) echo "Unknown option: $1"; usage; exit 1 ;;
39
+ esac
40
+ done
41
+
42
+ # Resolve the output directory after arg parsing. With --stdout (i.e. when
43
+ # the MCP server calls us) default to a temp dir — an agent calling these
44
+ # tools repeatedly must not fill the user's Desktop with report folders.
45
+ # An explicit --out always wins.
46
+ if [[ -z "$OUTDIR" ]]; then
47
+ if [[ "$STDOUT_MODE" -eq 1 ]]; then
48
+ OUTDIR=$(mktemp -d "${TMPDIR:-/tmp}/mac-backup.XXXXXX")
49
+ else
50
+ OUTDIR="$HOME/Desktop/mac-backup-$(date +%Y%m%d-%H%M%S)"
51
+ fi
52
+ fi
53
+
54
+ mkdir -p "$OUTDIR"
55
+ REPORT="$OUTDIR/report.txt"
56
+
57
+ section() {
58
+ echo
59
+ echo "============================================================"
60
+ echo "$1"
61
+ echo "============================================================"
62
+ }
63
+
64
+ JOBS_DIR=$(mktemp -d "${TMPDIR:-/tmp}/mac-diag-jobs.XXXXXX")
65
+ trap 'rm -rf "$JOBS_DIR"' EXIT
66
+ JOB_FILES=()
67
+ JOB_PIDS=()
68
+
69
+ # Runs each check concurrently in the background instead of sequentially.
70
+ run() {
71
+ local title="$1"
72
+ shift
73
+
74
+ local timeout_secs=20
75
+
76
+ local outfile="$JOBS_DIR/${#JOB_FILES[@]}.txt"
77
+ JOB_FILES+=("$outfile")
78
+
79
+ echo "Running: $title" >&2
80
+ {
81
+ section "$title"
82
+ echo "\$ $*"
83
+ echo
84
+ timeout "$timeout_secs" "$@" 2>&1 | tail -n 400 || echo "Command timed out or failed: $*"
85
+ } > "$outfile" &
86
+ JOB_PIDS+=("$!")
87
+ }
88
+
89
+ collect_jobs() {
90
+ local pid
91
+ for pid in "${JOB_PIDS[@]}"; do
92
+ wait "$pid" 2>/dev/null || true
93
+ done
94
+ local f
95
+ for f in "${JOB_FILES[@]}"; do
96
+ cat "$f" >> "$REPORT"
97
+ done
98
+ }
99
+
100
+ echo "Writing report to: $REPORT" >&2
101
+
102
+ {
103
+ echo "macOS Backup (Time Machine) Health Report"
104
+ echo "Generated: $(date)"
105
+ echo "Host: $(hostname)"
106
+ echo "User: $(whoami)"
107
+ echo
108
+ sw_vers
109
+ } > "$REPORT"
110
+
111
+ # tmutil needs Full Disk Access for some verbs; normalize failures to
112
+ # "unknown"/"none" so findings degrade gracefully instead of lying.
113
+ # shellcheck disable=SC2016
114
+ run "Time Machine configuration and status" \
115
+ bash -c '
116
+ dest=$(tmutil destinationinfo 2>/dev/null | grep -E "^(Name|Mount Point)" | sed "s/^[^:]*: *//" | paste -sd " / " - || true)
117
+ echo "DESTINATION: ${dest:-none}"
118
+ running=$(tmutil status 2>/dev/null | grep -c "\"Running\" = 1" || true)
119
+ echo "BACKUP_RUNNING: $([ "$running" -gt 0 ] && echo yes || echo no)"
120
+ auto=$(defaults read /Library/Preferences/com.apple.TimeMachine AutoBackup 2>/dev/null || echo unknown)
121
+ echo "AUTO_BACKUP: $auto"
122
+ '
123
+
124
+ # Last backup age: the latestbackup path ends in YYYY-MM-DD-HHMMSS.
125
+ # shellcheck disable=SC2016
126
+ run "Last successful backup" \
127
+ bash -c '
128
+ latest=$(tmutil latestbackup 2>/dev/null || true)
129
+ if [[ -z "$latest" ]]; then
130
+ echo "LAST_BACKUP: none"
131
+ echo "LAST_BACKUP_AGE_DAYS: none"
132
+ else
133
+ echo "LAST_BACKUP: $latest"
134
+ stamp=$(basename "$latest")
135
+ epoch=$(date -j -f "%Y-%m-%d-%H%M%S" "$stamp" "+%s" 2>/dev/null || echo 0)
136
+ if [[ "$stamp" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{6}$ ]] && (( epoch > 0 )); then
137
+ echo "LAST_BACKUP_AGE_DAYS: $(( ($(date +%s) - epoch) / 86400 ))"
138
+ else
139
+ echo "LAST_BACKUP_AGE_DAYS: unknown"
140
+ fi
141
+ fi
142
+ '
143
+
144
+ # shellcheck disable=SC2016
145
+ run "Local APFS snapshots" \
146
+ bash -c 'n=$(tmutil listlocalsnapshots / 2>/dev/null | grep -c "com.apple.TimeMachine" || true); echo "LOCAL_SNAPSHOTS: $n"'
147
+
148
+ collect_jobs
149
+
150
+ # Machine-readable findings, parsed only from the normalized KEY: lines.
151
+ FINDINGS=$(
152
+ section "Machine-readable findings"
153
+
154
+ if grep -q '^DESTINATION: none' "$REPORT"; then
155
+ finding CRIT backup "no Time Machine destination configured — data is not being backed up"
156
+ fi
157
+
158
+ if grep -q '^AUTO_BACKUP: 0' "$REPORT"; then
159
+ finding WARN backup "Time Machine automatic backups are disabled"
160
+ fi
161
+
162
+ age=$(grep -oE '^LAST_BACKUP_AGE_DAYS: [0-9]+' "$REPORT" | grep -oE '[0-9]+' | head -1 || true)
163
+ if grep -q '^LAST_BACKUP: none' "$REPORT" && ! grep -q '^DESTINATION: none' "$REPORT"; then
164
+ finding WARN backup "a destination is configured but no completed backup was found"
165
+ elif [[ "$age" =~ ^[0-9]+$ ]]; then
166
+ if (( age > 7 )); then
167
+ finding CRIT backup "last successful Time Machine backup is ${age} days old"
168
+ elif (( age > 3 )); then
169
+ finding WARN backup "last successful Time Machine backup is ${age} days old"
170
+ else
171
+ finding INFO backup "last successful Time Machine backup is ${age} day(s) old"
172
+ fi
173
+ fi
174
+
175
+ if grep -q '^BACKUP_RUNNING: yes' "$REPORT"; then
176
+ finding INFO backup "a Time Machine backup is running right now"
177
+ fi
178
+
179
+ snaps=$(grep -oE '^LOCAL_SNAPSHOTS: [0-9]+' "$REPORT" | grep -oE '[0-9]+' | head -1 || true)
180
+ if [[ "$snaps" =~ ^[0-9]+$ ]] && (( snaps > 0 )); then
181
+ finding --suggest "storage_breakdown" INFO backup "${snaps} local Time Machine snapshot(s) present — they consume purgeable disk space"
182
+ else
183
+ finding INFO backup "no local Time Machine snapshots"
184
+ fi
185
+ )
186
+ printf '%s
187
+ ' "$FINDINGS" >> "$REPORT"
188
+
189
+ cat <<EOF | tee -a "$REPORT" >/dev/null
190
+
191
+ ============================================================
192
+ Suggested interpretation
193
+ ============================================================
194
+
195
+ 1. No destination or automatic backups off are the critical findings —
196
+ everything else is about freshness.
197
+ 2. Local snapshots are normal and auto-managed, but on a nearly-full disk
198
+ they are reclaimable space (see storage_breakdown).
199
+ 3. If tmutil shows "unknown" values, the calling process likely lacks Full
200
+ Disk Access — the report says so rather than guessing.
201
+
202
+ EOF
203
+
204
+ if [[ "$STDOUT_MODE" -eq 1 ]]; then
205
+ cat "$REPORT"
206
+ else
207
+ echo "Done."
208
+ echo "Report saved to:"
209
+ echo "$REPORT"
210
+ fi
@@ -0,0 +1,203 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ # shellcheck source=mac_diagnostics_mcp/scripts/lib-findings.sh
5
+ source "$(dirname "$0")/lib-findings.sh"
6
+
7
+ STDOUT_MODE=0
8
+ OUTDIR=""
9
+
10
+ usage() {
11
+ cat <<EOF
12
+ mac-battery.sh
13
+
14
+ Check macOS battery health, cycle count, and charging state (MacBook only).
15
+
16
+ Usage:
17
+ $0 [options]
18
+
19
+ Options:
20
+ --out PATH Output folder (default: timestamped on Desktop)
21
+ --stdout Print report to stdout when done (used by MCP server)
22
+ -h, --help Show help
23
+ EOF
24
+ }
25
+
26
+ while [[ $# -gt 0 ]]; do
27
+ case "$1" in
28
+ --out) OUTDIR="$2"; shift 2 ;;
29
+ --stdout) STDOUT_MODE=1; shift ;;
30
+ -h|--help) usage; exit 0 ;;
31
+ *) echo "Unknown option: $1"; usage; exit 1 ;;
32
+ esac
33
+ done
34
+
35
+ # Resolve the output directory after arg parsing. With --stdout (i.e. when
36
+ # the MCP server calls us) default to a temp dir — an agent calling these
37
+ # tools repeatedly must not fill the user's Desktop with report folders.
38
+ # An explicit --out always wins.
39
+ if [[ -z "$OUTDIR" ]]; then
40
+ if [[ "$STDOUT_MODE" -eq 1 ]]; then
41
+ OUTDIR=$(mktemp -d "${TMPDIR:-/tmp}/mac-battery.XXXXXX")
42
+ else
43
+ OUTDIR="$HOME/Desktop/mac-battery-$(date +%Y%m%d-%H%M%S)"
44
+ fi
45
+ fi
46
+
47
+
48
+ mkdir -p "$OUTDIR"
49
+ REPORT="$OUTDIR/report.txt"
50
+
51
+ section() {
52
+ echo
53
+ echo "============================================================"
54
+ echo "$1"
55
+ echo "============================================================"
56
+ }
57
+
58
+ JOBS_DIR=$(mktemp -d "${TMPDIR:-/tmp}/mac-diag-jobs.XXXXXX")
59
+ trap 'rm -rf "$JOBS_DIR"' EXIT
60
+ JOB_FILES=()
61
+ JOB_PIDS=()
62
+
63
+ # Runs each check concurrently instead of sequentially so total wall time
64
+ # is bounded by the slowest single command rather than their sum — a
65
+ # sequential run of several ~45s-bounded checks can exceed the MCP
66
+ # client's ~240s call timeout.
67
+ run() {
68
+ local title="$1"
69
+ shift
70
+
71
+ local timeout_secs=20
72
+ case "$*" in
73
+ *"log show"*|*"pmset -g log"*) timeout_secs=35 ;;
74
+ esac
75
+
76
+ local outfile="$JOBS_DIR/${#JOB_FILES[@]}.txt"
77
+ JOB_FILES+=("$outfile")
78
+
79
+ echo "Running: $title" >&2
80
+ {
81
+ section "$title"
82
+ echo "\$ $*"
83
+ echo
84
+ timeout "$timeout_secs" "$@" 2>&1 | tail -n 400 || echo "Command timed out or failed: $*"
85
+ } > "$outfile" &
86
+ JOB_PIDS+=("$!")
87
+ }
88
+
89
+ collect_jobs() {
90
+ local pid
91
+ for pid in "${JOB_PIDS[@]}"; do
92
+ wait "$pid" 2>/dev/null || true
93
+ done
94
+ local f
95
+ for f in "${JOB_FILES[@]}"; do
96
+ cat "$f" >> "$REPORT"
97
+ done
98
+ }
99
+
100
+ echo "Writing report to: $REPORT" >&2
101
+
102
+ {
103
+ echo "macOS Battery Health Diagnostic Report"
104
+ echo "Generated: $(date)"
105
+ echo "Host: $(hostname)"
106
+ echo "User: $(whoami)"
107
+ echo
108
+ sw_vers
109
+ } > "$REPORT"
110
+
111
+ run "Current battery status" pmset -g batt
112
+
113
+ run "Battery details (ioreg)" \
114
+ bash -c "ioreg -rn AppleSmartBattery | grep -Ei 'CurrentCapacity|MaxCapacity|DesignCapacity|CycleCount|IsCharging|ExternalConnected|Temperature|Voltage|Amperage|TimeRemaining|BatteryHealth|FullyCharged|AdapterDetails'"
115
+
116
+ run "Power source info (system_profiler)" \
117
+ system_profiler SPPowerDataType
118
+
119
+ run "Thermal state" \
120
+ pmset -g thermlog
121
+
122
+ run "Recent battery / charging events (pmset log)" \
123
+ bash -c "pmset -g log | grep -Ei 'charge|battery|ac power|dc power|thermal|sleep|wake' | tail -100"
124
+
125
+ collect_jobs
126
+
127
+ # Machine-readable findings for agent consumers, parsed from the report.
128
+ FINDINGS=$(
129
+ section "Machine-readable findings"
130
+
131
+ if ! grep -q "AppleSmartBattery" "$REPORT"; then
132
+ finding INFO battery "no battery detected — desktop Mac"
133
+ else
134
+ health_pct=$(grep -oE 'Maximum Capacity: [0-9]+%' "$REPORT" | grep -oE '[0-9]+' | head -1 || true)
135
+ if [[ -n "$health_pct" ]]; then
136
+ if (( health_pct < 80 )); then
137
+ finding WARN battery "maximum capacity is ${health_pct}% of design — battery is worn"
138
+ else
139
+ finding INFO battery "maximum capacity is ${health_pct}% of design"
140
+ fi
141
+ fi
142
+
143
+ cycles=$(grep -oE '"CycleCount" = [0-9]+' "$REPORT" | grep -oE '[0-9]+' | head -1 || true)
144
+ if [[ -n "$cycles" ]]; then
145
+ if (( cycles > 800 )); then
146
+ finding WARN battery "cycle count is ${cycles} — approaching the 1000-cycle design limit"
147
+ else
148
+ finding INFO battery "cycle count is ${cycles} (design limit ~1000)"
149
+ fi
150
+ fi
151
+
152
+ condition=$(grep -oE 'Condition: .*' "$REPORT" | head -1 | sed 's/Condition: //' || true)
153
+ if [[ -n "$condition" && "$condition" != "Normal" ]]; then
154
+ finding WARN battery "battery condition: ${condition}"
155
+ fi
156
+ fi
157
+ )
158
+ printf '%s
159
+ ' "$FINDINGS" >> "$REPORT"
160
+
161
+ cat <<EOF | tee -a "$REPORT" >/dev/null
162
+
163
+ ============================================================
164
+ Suggested interpretation
165
+ ============================================================
166
+
167
+ 1. Battery health (system_profiler SPPowerDataType):
168
+ - Condition: Normal / Service Recommended / Replace Soon / Replace Now
169
+ - Cycle count: typical max 1000 cycles on M-series MacBooks
170
+ - Maximum Capacity %: current vs design capacity
171
+
172
+ 2. Key ioreg fields:
173
+ - MaxCapacity / DesignCapacity × 100 = approximate health %
174
+ - CycleCount: total full charge cycles (< 1000 is healthy)
175
+ - Temperature: in hundredths of Celsius (30000 = 30°C)
176
+ - IsCharging: 1 = currently charging
177
+ - ExternalConnected: 1 = adapter plugged in
178
+
179
+ 3. Battery draining faster than expected:
180
+ - Check pmset -g assertions for sleep blockers
181
+ - Run mac-sleep-investigate.sh to check unexpected wakes
182
+ - Check Activity Monitor → Energy tab for high-drain processes
183
+
184
+ 4. Optimized Battery Charging:
185
+ - macOS learns charging patterns and holds at 80% when possible
186
+ - Disable in System Settings → Battery → Battery Health
187
+
188
+ 5. For detailed real-time power monitoring:
189
+ sudo powermetrics --samplers smc,battery -n 1
190
+
191
+ 6. If battery not detected or behaving strangely:
192
+ - SMC reset: shut down → hold Shift+Control+Option+Power for 10s
193
+ - PRAM/NVRAM reset: hold Cmd+Option+P+R at boot
194
+
195
+ EOF
196
+
197
+ if [[ "$STDOUT_MODE" -eq 1 ]]; then
198
+ cat "$REPORT"
199
+ else
200
+ echo "Done."
201
+ echo "Report saved to:"
202
+ echo "$REPORT"
203
+ fi