io.github.zw008/vmware-debug
<!-- mcp-name: io.github.vmware-skills/vmware-debug -->
# VMware Debug
> ⚠️ **Work in progress** — the core (event correlation engine, MCP tools, CLI)
> is built and tested; README, `server.json`, full reference docs, and packaging
> polish are still landing. Not yet published to PyPI.
> **Disclaimer**: Community-maintained open-source project, **not affiliated with,
> endorsed by, or sponsored by VMware, Inc. or Broadcom Inc.** "VMware" and
> "vSphere" are trademarks of Broadcom. Source is publicly auditable under the MIT
> license.
The diagnostic brain of the VMware skill family. You bring the symptom (an error,
a log dump, a slow VM); this skill runs a systematic investigation, correlates
events from the other skills into one timeline, ranks root-cause hypotheses, and
tells you what to check next. It is **read-only** — it never changes anything and
never executes fixes. Remediation is routed to `vmware-aiops` (single op) or
`vmware-pilot` (multi-step, gated), mirroring the `vmware-harden → vmware-pilot`
advisor/executor split.
See [`skills/vmware-debug/SKILL.md`](skills/vmware-debug/SKILL.md) for the full
methodology, the event-envelope contract, and symptom routing.
## MCP tools
| Tool | What |
|---|---|
| `incident_timeline` | [READ] Correlate pre-fetched events → timeline + spikes + ranked hypotheses + next-check ideas |
| `list_symptom_categories` | [READ] List recognised symptom categories + what to check for each |
## Offline / Air-Gapped Install (from source)
This project uses the modern PEP 517 build system (hatchling), so there is **no
`setup.py`** by design — that is expected, not a missing file. If you cloned the
source and hit `ERROR: File "setup.py" or "setup.cfg" not found ... editable mode
currently requires a setuptools-based build`, your `pip` is older than 21.3 and
cannot do an *editable* (`-e`) install with a non-setuptools backend. Editable
mode is a developer convenience, not needed to run the tool — do one of:
```bash
# From the source tree — a normal (non-editable) install builds a wheel:
pip install . # NOT pip install -e .
# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .
```
For a **truly air-gapped host**, build the wheels on a connected machine and copy
them over — the target then needs no network:
```bash
# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist # → dist/*.whl (or: uv build, for just this package)
# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-debug
```
## License
MIT.
TDQS
Scored across 14 tools
Each tool has a clearly defined role, and the case_* family is well delineated: open, get, submit evidence, record gap, grade, close, etc. The main ambiguity is between incident_timeline and case_timeline, and between list_symptom_categories and case_plan, though the descriptions do enough to distinguish them in most contexts.
Most tools share the case_ prefix, making the family recognizable, but the naming scheme mixes verb-first names like case_open and case_get with noun-style names like case_timeline, case_readiness, and case_knowledge. The two non-case tools also break the pattern: incident_timeline is noun-only and list_symptom_categories reverses the prefix ordering.
With 14 tools, the set is well-scoped for a case-investigation and evidence-grading workflow. Each tool occupies a distinct role in the lifecycle, and none feel redundant or decorative.
The tool set covers the full investigation workflow: open, plan, collect evidence, record gaps, manage hypotheses, timeline correlation, grading, and closing, plus supporting introspection tools for readiness, knowledge, and symptom categories. The intentional lack of fetch/update/delete is consistent with the server's stated role as an analysis and ledger layer over external data-source skills.