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.
- mac_diagnostics_mcp/__init__.py +0 -0
- mac_diagnostics_mcp/runner.py +129 -0
- mac_diagnostics_mcp/scripts/lib-assess.sh +68 -0
- mac_diagnostics_mcp/scripts/lib-findings.sh +59 -0
- mac_diagnostics_mcp/scripts/mac-backup.sh +210 -0
- mac_diagnostics_mcp/scripts/mac-battery.sh +203 -0
- mac_diagnostics_mcp/scripts/mac-cpu-memory.sh +265 -0
- mac_diagnostics_mcp/scripts/mac-crashes.sh +399 -0
- mac_diagnostics_mcp/scripts/mac-disk-health.sh +227 -0
- mac_diagnostics_mcp/scripts/mac-mcp-servers.sh +452 -0
- mac_diagnostics_mcp/scripts/mac-network.sh +218 -0
- mac_diagnostics_mcp/scripts/mac-node-packages.sh +272 -0
- mac_diagnostics_mcp/scripts/mac-node-update.sh +328 -0
- mac_diagnostics_mcp/scripts/mac-quick-health.sh +216 -0
- mac_diagnostics_mcp/scripts/mac-security.sh +291 -0
- mac_diagnostics_mcp/scripts/mac-sleep-investigate.sh +305 -0
- mac_diagnostics_mcp/scripts/mac-software-update.sh +241 -0
- mac_diagnostics_mcp/scripts/mac-startup-items.sh +238 -0
- mac_diagnostics_mcp/scripts/mac-storage.sh +215 -0
- mac_diagnostics_mcp/scripts/mac-wifi.sh +204 -0
- mac_diagnostics_mcp/server.py +456 -0
- mac_diagnostics_mcp/state.py +150 -0
- mac_diagnostics_mcp/triage.py +182 -0
- mac_diagnostics_mcp-0.5.0.dist-info/METADATA +322 -0
- mac_diagnostics_mcp-0.5.0.dist-info/RECORD +29 -0
- mac_diagnostics_mcp-0.5.0.dist-info/WHEEL +5 -0
- mac_diagnostics_mcp-0.5.0.dist-info/entry_points.txt +2 -0
- mac_diagnostics_mcp-0.5.0.dist-info/licenses/LICENSE +21 -0
- 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
|