# Computer Expert — Alexa+ Agent Skill

A self-hosted MCP server and web simulator that turns the `diannao-dashen` computer-diagnostics skill into an agent that can inspect a Windows, macOS, or Linux machine **read-only first**.

This project was built for the **Amazon Developer Hackathon, Alexa+ track**. The hackathon FAQ states that Amazon's Alexa+ preview tools (Category SDK, MCP Toolkit, CLI, Web Simulator) are not available to hackathon participants, and explicitly allows a **self-hosted MCP server (or Agent Skill) demoed through your own web-based simulator**. This repository follows that path.

## What it does

The agent exposes eight MCP tools:

| Tool | What it does | Risk |
|---|---|---|
| `system_profile` | OS, machine, CPU, GPU, memory modules, disks, board, BIOS | R0 read-only |
| `system_baseline` | CPU, memory pressure, disk activity, top processes, startup items, thermal hints, power plan | R0 read-only |
| `diagnose` | Collects profile + baseline in parallel, classifies the symptom, extracts threshold findings (CPU, memory, disk, thermal, free space), and returns bounded next checks | R0 read-only |
| `scan_space` | Directory size, top-level usage, large files, empty dirs, duplicate candidates by size, file types | R0 read-only |
| `audit_startup` | Startup items, services, installed software (HKCU/HKLM + WOW6432Node), power plan | R0 queries; changes are R2/R3 and never automated |
| `check_disk_health` | Physical disk inventory and Windows SMART-style reliability counters (temperature, wear, errors, power-on hours); macOS/Linux disk info | R0 queries; no self-test/repair; replacement is R3 manual |
| `check_driver_updates` | Current OS/GPU/driver versions and the three-tier official source chain | R0 queries; installation is R3 manual |
| `plan_upgrade` | Hardware profile, bottleneck signals, compatibility gates, four upgrade tiers | R0 analysis; purchase/disassembly/BIOS is R3 |

The MCP server also exposes the translated skill as resources and a `diagnose_computer` prompt. Every result includes a `voice_summary` for a screenless/first-turn answer, and the web simulator has a voice mode with speech synthesis, optional speech recognition, and a per-result Speak button.

The sidebar lists the eight tools as the server reports them, so the tool surface on screen always matches the server's actual registration.

## Quick start

```bash
pip install -r requirements.txt

# One command: starts both the MCP server and the web simulator
python run_demo.py
```

`requirements-demo.txt` holds the extra dependencies used only to regenerate the demo video and screenshots (`playwright`, `edge-tts`); `ffmpeg` must also be on `PATH`.

Or run the two processes separately:

```bash
python -m mcp_server --host 127.0.0.1 --port 8000
python -m uvicorn web.app:app --host 127.0.0.1 --port 8080
```

Open http://127.0.0.1:8080. The MCP endpoint is `http://127.0.0.1:8000/mcp` (Streamable HTTP).

## Architecture

```text
Browser (web simulator)
        |
        v
FastAPI /api/ask  --- MCP client (Streamable HTTP) --->  MCP server
                                                            |
                                                            +-- system_profile
                                                            +-- system_baseline
                                                            +-- diagnose
                                                            +-- scan_space
                                                            +-- audit_startup
                                                            +-- check_driver_updates
                                                            +-- plan_upgrade
                                                            |
                                                            v
                                                  Native OS commands
                                                  (PowerShell / macOS / Linux)
```

- `mcp_server/safety.py`: risk model, path validation, redaction, fixed PowerShell/command execution.
- `mcp_server/diagnostics.py`: cross-platform read-only diagnostics.
- `mcp_server/server.py`: MCP 2.x `MCPServer` with tools, resources, and a prompt.
- `web/app.py`: FastAPI backend + MCP client.
- `web/static/`: single-page simulator UI.
- `skill_en/`: English translation of the skill.
- `skill_en/` is the only skill pack in this repository. The Chinese original is archived outside the submission repo at `..\amazon_alexa_zh_source\`.

## Safety model

The skill uses a four-level risk model:

- **R0** — read-only, executed automatically. Scope and time bounds are stated first.
- **R1** — low risk, rebuildable; never executed here. Requires an exact execution order and approval.
- **R2** — medium risk, potentially irreversible; never executed here. Requires separate category-level approval.
- **R3** — high risk (admin/root, drivers, firmware, BIOS, registry, services, partitions, boot); never executed. Official manual guidance only.

The server enforces additional guards:

- Scan roots cannot be a drive root, the home directory, a system directory, an application library, a credential directory, a symlink, junction, reparse point, UNC path, mapped network drive, mount root, or wildcard path. A rejected request returns a structured refusal that names the reason — the guard never opens the directory first.
- Scans are bounded by depth, entry count, and time; links, junctions, reparse points, and cross-device mounts are skipped and counted.
- Only fixed, read-only commands are used. User input is never interpolated into a shell; PowerShell is resolved from the system directory, not PATH.
- Serial numbers, Apple hardware UUIDs, account names, emails, IP/MAC addresses, host names, and device instance tails are redacted.
- The MCP server only binds to loopback; non-loopback addresses are refused. A remote deployment needs a production gateway with OAuth, TLS, and rate limiting.
- No deletion, move, install, update, uninstall, service change, registry change, or reboot is performed by any tool.

## Migration from the original skill

| Original | English / runtime |
|---|---|
| `SKILL.md` | `skill_en/SKILL.md`; also the MCP server instructions and `skill://diannao-dashen/SKILL.md` resource |
| `README.md` | `skill_en/README.md`; also the `skill://diannao-dashen/README.md` resource |
| `windows.md` / `macos.md` / `linux.md` | English platform command guides in `skill_en/`; implemented by the diagnostics tools |
| `references/maintenance-and-files.md` | Risk tiers, consent, cleanup categories, file organization; enforced in code |
| `references/diagnosis-core.md` | Evidence levels, baseline, fault tree, confidence; used by `diagnose` |
| `references/software-driver-updates.md` | Three-tier source chain and no-install boundary; used by `check_driver_updates` |
| `references/hardware-upgrade.md` | Compatibility gates and four upgrade tiers; used by `plan_upgrade` |
| `references/search-and-sources.md` | Source policy and official whitelist; embedded in the driver/upgrade outputs |
| `agents/skill.yaml` | `skill_en/agents/skill.yaml` |

The original skill was installed with:

```bash
npx @astron-team/skillhub install diannao-dashen --registry https://skill.xfyun.cn
```

It is a Markdown-only skill (no scripts). The migration adds a deterministic tool layer so the agent can actually collect local evidence instead of only describing what to run.

## Translation

The complete core skill is translated into English under `skill_en/`:

- `SKILL.md`
- `README.md`
- `windows.md`
- `macos.md`
- `linux.md`
- `references/diagnosis-core.md`
- `references/maintenance-and-files.md`
- `references/software-driver-updates.md`
- `references/hardware-upgrade.md`
- `references/search-and-sources.md`
- `agents/skill.yaml`

The Chinese original is archived outside the submission repo for provenance. The submitted runtime is English-only and the MCP server does not load Chinese files.

## Demo flow (about 3 minutes)

1. Start `python run_demo.py`; show the MCP status, the eight registered tools, and the risk legend; turn voice mode on.
2. Click **Diagnose slow / hot PC**. Show the voice summary, checks table, threshold findings, bounded next checks, and the R0/R1/R2/R3 action table.
3. Click **Check disk health**. Show physical disks and SMART-style counters; point out the unknown-health caveat when counters are unavailable.
4. Enter a drive root such as `C:\` and click **Scan a folder**. Show the structured refusal: it names the reason and reports zero files opened and zero files changed.
5. Enter a narrow folder such as `E:\ShopBench\TICKET-4471` and click **Scan a folder**. Show coverage, the top-level usage, large files, duplicate candidates, the four cleanup categories, and the fact that nothing was deleted.
6. Click **Audit startup items**. Show startup items, services, installed software, and the R2/R3 action table with next steps.
7. Click **Check driver context**. Show the current driver and the three-tier official chain, with "no download, no install".
8. Click **Export packet** to download the JSON evidence packet with the disclaimer.
9. Close with the safety invariant: R0 evidence is automatic; R1/R2/R3 are plans or manual guidance only.

A shot-by-shot script is in `docs/demo-script.md`; the recorded narration, timings, and captions are in `docs/demo-video-script.md` and are generated from `tools/narration.py`.

## Demo assets

```bash
python demo/make_fixtures.py        # create the scan fixtures (sparse, ~1.6 GB declared)
python demo/make_fixtures.py --clean

python tools/tts.py                 # synthesize the English narration (edge-tts)
python tools/record_demo.py         # drive the live simulator and record the screen
python tools/assemble_video.py      # narration + burned-in captions -> demo-final.mp4
python tools/shots.py               # still screenshots of the simulator
python tools/run_demo_ports.py      # run the demo on explicit ports
```

The recorder fires each action at the absolute second computed from the narration durations, so the audio and the on-screen state cannot drift apart. `tools/run_demo_ports.py` exists because the default ports are often taken on a developer machine.

## Tests

```bash
python -m unittest discover -s tests -v
python tests/smoke_live.py   # starts the MCP server and calls system_profile
python tests/smoke_web.py    # starts MCP + web app and calls /api/ask
```

The test suite covers the safety guards (including control characters, credential directories, Windows reserved names, and Apple serial redaction), read-only diagnostics, threshold findings, the four-tier upgrade plan, routing, structured scan refusals, MCP tool registration, a live Streamable HTTP call that asserts MCP `2025-11-25`, and the web API. See `docs/evaluation.md` for the test matrix and measured latency.

## Status and next steps

Done:

- Installed and preserved the original skill.
- Translated the complete skill into English.
- Built a working MCP server with eight tools, four resource endpoints (including a document template), and one prompt.
- Built a working web simulator with risk badges, findings, voice summaries, a voice mode, a Speak button, a live tool list, and a structured refusal card.
- Verified MCP Streamable HTTP (negotiated `2025-11-25`), the web API, prompts, and resources; captured a clean home-screen render in `docs/shots/01-home.png`.
- All 51 test methods pass (50 executed, 1 POSIX-only skip on Windows); both live smoke scripts pass.
- Added an English-only threat model, evaluation, positioning brief, and packet schema: `docs/threat-model.md`, `docs/evaluation.md`, `docs/positioning.md`, `docs/packet-schema.md`.
- Completed three mock-judge rounds and wrote the English defense cheat sheet: `pre/defense-cheatsheet.md`.
- Recorded the demo video: `docs/video/demo-computer-expert.mp4` (2:43, English narration, burned-in captions, sidecar `docs/video/demo-captions.srt`), driven by `tools/narration.py` → `tools/tts.py` → `tools/record_demo.py` → `tools/assemble_video.py`.
- Wrote the submission materials: `docs/submission.md`, `docs/product-feedback.md`, `docs/friction-log.md`.
- Added reproducible scan fixtures and the recording toolchain: `demo/make_fixtures.py`, `tools/`.

Pending for the hackathon submission:

- Publish the repository on GitHub with an open-source license (or share a private repo with the reviewers listed in the rules).
- Upload `docs/video/demo-computer-expert.mp4` to YouTube or Vimeo as a public video.
- Submit on Devpost before the Amazon Developer Hackathon deadline (October 23, 2026, 12:00 pm PT).
- Optional: produce a production Alexa+ add-on manifest once Amazon grants access to the gated preview tools; the current self-hosted MCP + simulator path is explicitly allowed by the hackathon FAQ.

See `docs/submission-checklist.md` for the exact Amazon track requirements and evidence links.

## License

MIT. The skill content is the user's own work; the original Chinese copy is archived outside the submission repo for provenance.