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:

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.

Related MCP server: IT-MCP

Quick start

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:

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

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

The original skill was installed with:

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

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

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.