WinKit

Windows observability for AI agents. WinKit is a read-only, local-first Model Context Protocol (MCP) server that gives coding agents a structured, permissioned view of the Windows machine they run on - and the ability to answer real questions about it without guessing.

Your machine, visible to your agent. No cloud, no telemetry, no writes.

$ opencode --mcp-config examples/mcp/opencode.json

  User: Why did my PC restart overnight?
  Agent: > shutdown_analysis(since_minutes=720)
         { boots: 1, unexpected_shutdowns: 1, power_losses: 1,
           last_shutdown_kind: "power_loss",
           events: [6008 @ 2026-08-18T20:13:47Z, 41 @ ...] }
         "You had a power loss at 8:13 PM yesterday - the machine
          did not shut down cleanly. No BSOD was logged."

That is the whole pitch: instead of an agent hallucinating a Get-WinEvent filter or telling you to "check Event Viewer", it reads the real event log through a schema-driven tool and answers with evidence.

Install in 10 seconds

npx --yes @winkit/mcp@latest install --yes   # registers MCP + skill in every detected agent
npx --yes @winkit/mcp@latest doctor          # verify - all checks should PASS

One command detects OpenCode, Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, Zed, Cline, Roo Code and Continue, merges the WinKit MCP entry with a timestamped .bak backup, and drops the companion skill winkit-developer-debugging into every agent's skills folder (so your agent automatically knows when to call WinKit). Add --without-skill for MCP-only, --list to preview, or --json for machine output. See docs/installation.md for manual and per-client setup.

Related MCP server: windows-admin-mcp

Without / With

❌ Without WinKit - an agent on Windows is blind. It guesses PowerShell syntax, invents registry paths, assumes service names, and answers "why is my disk full?" with generic advice and no data.

✅ With WinKit - the agent reads live process, service, event-log, network, storage, and registry state through 51 compact, read-only tools, then reports measurements, not guesses.

Highlights

• 51 MCP tools, all read-only: system, processes, network, storage, hardware, power, services, event logs, windows, registry, Wi-Fi, bounded filesystem reads, environment/update posture, and the developer workflow. Tool profiles (core 6, developer/full 51) keep the agent's tool surface lean.

• Answers questions, not just queries - system_diagnose, crash_history, shutdown_analysis, diagnose_workspace, and diagnose_local_webapp are complete problem-solvers: "what crashed last night?", "why is the fan spinning?", "why is my port stale?".

• Evidence-first diagnostics - every report separates what was measured from what is interpreted: ranked findings, stable finding IDs, and a confirmed/observed/possible confidence language that never claims causality from timing. Pure threshold logic: no LLM, no randomness, no fabricated claims.

• Honest completeness - system_diagnose reports evidence_completeness: "full" | "limited" when something could not be measured. WinKit tells you what it could not see.

• Read-only by construction - every tool is a read; there are no write, execute, or delete paths anywhere in the codebase.

• Local-first, zero telemetry - stdio transport, runs as your user, nothing is persisted and nothing leaves the machine.

• Provider architecture - everything sits behind the WindowsBackend trait; a mock backend plus deterministic fixtures power the test suite (cargo test --features mocks) with no machine dependency.

• Hardened by construction - bounded results, per-tool timeouts, payload caps, an 8 MiB transport frame cap, strict JSON schema validation, and stdout kept protocol-clean.

• npm distribution - npx --yes @winkit/mcp@latest doctor verifies the install; native Windows binaries ship for x64 and ARM64, and the launcher picks the right one by process.arch.

• Current MCP protocol - WinKit negotiates 2025-06-18, 2025-03-26, or 2024-11-05 during initialize, echoing whichever your client requests, so modern clients stop falling back to the oldest common version.

• Elevation-aware from the first minute - winkit doctor reports whether your session is elevated and names exactly which reads are privilege-gated, so a limited thermal or S.M.A.R.T. result is never a surprise.

Safety & privacy

This is the section to read twice, because it is the product.

• Read-only, always. Every tool is a read. The registry reader is allowlist-only (OS identity, startup programs, installed software) and never touches values. There are no write, execute, or delete code paths.

• No telemetry. No outbound calls, no update checks, no usage reports, no crash uploads. WinKit makes no network connections except a loopback probe when you ask it to inspect a local web app.

• Local-first. A stdio subprocess of your MCP client, running as your user, on your machine. No daemon, no server, no account.

• Bounded everywhere. Result caps, timeouts, payload caps, and a transport frame cap keep every tool fast and cheap for your agent's context window.

• Nothing persisted. WinKit has no history, no logs-to-disk, no state. Diagnostics sample in memory and report.

What WinKit does not do

• No file writes, no process termination, no service changes.

• No registry writes.

• No admin elevation - it runs at your privilege level and says so when a read needs more.

• No remote access; it cannot be reached over the network.

• No secrets are captured: event messages, command lines, and URLs are read where readable and reported bounded; credentials and secret-bearing fields are never returned.

Quick start

Requirements: Windows 10/11 (x64 or ARM64) and Node.js >= 18 (npm path) or Rust 1.75+ (from source).

npx --yes @winkit/mcp@latest doctor   # verify the install
npx --yes @winkit/mcp@latest install --yes   # register WinKit in every installed AI agent

install detects the coding agents already on the machine (OpenCode, Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, Zed, Cline, Roo Code, Continue) and merges the WinKit MCP entry into each one's config - surgically, with a timestamped .bak backup of every file it edits. Run it without --yes to confirm each runtime, or with --list to preview first.

Or build from source:

cargo build --release
.\target\release\winkit --help

WinKit runs as a stdio subprocess of your MCP client. Ready-made configs:

• OpenCode - examples/mcp/opencode.json

• Claude Code - examples/mcp/claude-code.json

• Any MCP client - examples/mcp/generic.json

{
  "mcpServers": {
    "winkit": {
      "command": "npx",
      "args": ["--yes", "@winkit/mcp@latest"]
    }
  }
}

On Windows, wrap npx with cmd /c in clients that need it: "command": "cmd", "args": ["/c", "npx", "--yes", "@winkit/mcp@latest"].

Without a config file, WinKit runs with safe defaults: read_only permission mode, both built-in providers enabled, and documented limits. See config/example.toml for the full surface and docs/installation.md for the complete setup story.

The tools

Every tool below is read-only. Full reference with argument schemas: docs/tools.md.

Try these prompts

• "Is my disk failing?" → disk_health + list_drives

• "What crashed last night?" → crash_history(since_minutes=720)

• "Did my PC shut down cleanly?" → shutdown_analysis

• "Why is the fan spinning?" → thermal_snapshot + hardware_snapshot

• "What's eating my RAM?" → system_health or system_diagnose

• "Why is my local server not reachable?" → diagnose_local_webapp

• "Show me the end of that log" → read_text_file(mode="tail")

• "What's eating disk space in D:\dev?" → directory_overview

• "Why won't my tool start?" → audit_path_env + dev_environment

• "Is a reboot pending?" → system_update_status

• "What starts with my PC, and what slows it down?" → startup_programs (enabled/disabled state, hidden autostarts, impact estimates)

Architecture

WinKit measures, WinKit interprets signals, WinKit ranks evidence-backed findings; the LLM explains them:

server (MCP over stdio, JSON-RPC 2.0, session lifecycle)
  +-- tools        (51 tool definitions + argument handling + registry)
  |    +-- providers (WindowsBackend / ApplicationProvider traits)
  |         +-- platform::windows (real Win32 implementations, windows-sys 0.59)
  +-- permissions  (modes, capabilities, policy, approval surface)
  +-- config       (winkit.toml, strict, deny-unknown-keys)
  +-- models       (unified data models shared by providers/tools/diagnostics)
  +-- diagnostics  (measurements -> signals -> ranked findings)

Layering rules are strict: the MCP surface never touches Win32 directly, and the Windows layer is testable through a mock backend. Deep dive: docs/architecture.md.

Permission model

Four modes (safe, read_only, approval, unrestricted) gate 14 v1 read capabilities, fail closed by default, and deny with a precise reason " an agent never guesses why a call was refused. safe and read_only grant every read capability; actions (none in v1 for Windows state) require the approval mode. See docs/permissions.md.

Performance

End-to-end median latency (release build, fresh process per call, includes startup and the MCP handshake):

Observation-window tools scale with their configured window, not system size; every other tool stays sub-100 ms regardless of how many processes or ports exist. Full table and methodology: docs/performance.md.

Known limitations

WinKit treats limits as first-class output, not bugs:

• Per-process CPU percent is a live sample, not a cumulative measure. list_processes reports cpu_percent: null; get_process samples a two-sample estimate with an explicit basis; aggregate views use a 1 s sample.

• Some Windows processes deny read access - they are still listed with null for the fields that could not be read, never dropped silently.

• Some reads are elevation-gated (e.g. some ACPI thermal zones and S.M.A.R.T. attributes) - reported as permission_denied or limited completeness with a reason.

• Diagnostics distinguish measured from unmeasured - reports carry evidence_completeness and limitations so agents do not over-read a partial view.

Development

cargo check                 # compile checks
cargo test --features mocks # full test suite (no machine needed)
cargo clippy --all-targets  # lint
cargo test --features mocks --test eval   # 18-scenario failure suite

Opt-in live tests (WINKIT_LIVE_WINDOWS=1) run against the real machine. See docs/development.md and docs/release.md.

Documentation

• docs/installation.md - build, configure, connect to an MCP client

• docs/tools.md - full tool reference with arguments

• docs/agent-workflows.md - end-to-end recipes: prompt, tool sequence, how to read the report

• docs/platform-support.md - OS/architecture matrix, privilege table, protocol versions

• docs/troubleshooting.md - symptom-first guide for install, doctor, tools, and clients

• docs/faq.md - short answers to common questions

• docs/diagnostics.md - the evidence-first report shape and score formulas

• docs/security.md - threat model and mitigations

• docs/permissions.md - modes, capabilities, policy table

• docs/architecture.md - layering, data flow, provider model

• docs/configuration.md - every config key and default

• docs/performance.md - benchmark methodology and full table

• docs/mcp-integration.md - protocol versioning and client setup examples

• SECURITY.md - security policy

• CHANGELOG.md - release history

Contributing

Contributions are welcome - see CONTRIBUTING.md.

License

MIT - see LICENSE. WinKit is local-first and open source; it contains no telemetry and makes no network calls except the loopback probe when you ask it to inspect a local web app.