WCP — Workstation Capability Protocol

An open, vendor-neutral standard for how AI agents discover, understand, and operate a whole workstation — under governed, audited, revocable authority.

Status: v0.1 — reference implementation complete, conformance-gated, cross-OS CI green. The spec is a draft and may still change.

WCP lets any MCP-speaking AI (Claude Desktop, Claude Code, …) do far more than run shell commands: it can perceive your machine (accessibility tree, screen, windows), operate it by meaning (invoke a menu command, fill a field — not pixel-guessing), manage the whole system (processes, packages, services, containers, VMs, git, networking), and hand you back a verifiable knowledge graph of everything it did. Every action is scope-gated, sandbox-confined where it touches files, and recorded in a hash-chained tamper-evident audit log.

Try it in 60 seconds → QUICKSTART.md. The normative spec → SPEC.md.

---

What it can do

35 capability families · 258 operations, spanning the full WCP Level 5 catalog. Every family has native macOS/Linux/Windows adapters (or honestly reports WCP_BACKEND_UNAVAILABLE where an OS or tool can't provide it — it never fakes a result).

Domain	Families (op count)
Perception & UI	ax accessibility tree (19) · window (11) · screen capture+OCR (2) · clipboard (5) · input synthesis (6)
Files & search	fs (18) · search files/content, sandbox-confined (4)
Execution & processes	exec run + PTY sessions (6) · process list/tree/monitor/signal (10)
System & hardware	system self-describe (8) · hardware cpu/gpu/usb/bluetooth/sensors (10) · host power/session (12) · net (12) · storage (6) · display (6) · audio (6)
Apps & automation	apps launch/quit/activate (7) · osa AppleScript/JXA (1)
Packages, services, jobs	packages brew/apt/winget (7) · services launchd/systemd/SCM (7) · scheduler cron/launchd/schtasks (5)
Dev & infrastructure	git (12) · container docker/podman (8) · vm VBox/libvirt (6) · k8s kubectl (8) · browser Chrome DevTools (7)
Identity, security, time	identity (4) · security permissions/audit/policy (7) · events subscriptions (4) · timeline (5)
Cognition & semantics	workspace root/orientation (7) · goal plan+execute (4) · ai tools/memory (7) · graph — the RDF/PROV-O knowledge-graph capstone (8)
Media	camera devices/snapshot/record (3)

The full operation catalog and per-op scopes live in SPEC.md and spec/; machine-readable schemas are in schemas/.

The knowledge-graph capstone

wcp.graph projects the entire workstation self-model (workstation → families → operations → scopes → principals) plus a PROV-O provenance overlay derived from the audit log into a typed, URI-addressed RDF graph. It ships a zero-dependency triple-pattern + traversal query engine and N-Triples / Turtle export that loads straight into GraphDB or any SPARQL store (optional live SPARQL via the graph extra). An AI can turn your running machine — and a verifiable record of what it just did to it — into a graph you can query.

---

Installation

WCP ships two Python packages (both target Python ≥ 3.10, and both run on Linux, macOS, and Windows):

• wcpd — the reference server (the thing you run and connect an AI to).
• wcp-conformance — the standalone test suite that certifies any WCP endpoint.

From PyPI

Publishing is wired via GitHub Actions trusted publishing and fires on a v* tag. Until the first release tag is pushed, install from source (below).

pip install wcp                 # the reference server
pip install "wcp[graph]"        # + live SPARQL (rdflib) for wcp.graph.export
wcpd --help

Optional extras:

Extra	Enables
wcp[graph]	Live SPARQL queries in wcp.graph.export (via rdflib). Core graph build/query/traverse/export-to-N-Triples is always available with zero dependencies.
wcp[linux-ax]	The pip half (PyGObject) of the Linux accessibility backend. pyatspi itself comes from your OS package manager (python3-pyatspi / at-spi2-core).
wcp[windows-ax]	The COM binding (comtypes) for the Windows UI Automation accessibility backend.

From source

git clone https://github.com/kchemorion/WorkstationCapabilityProtocol.git
cd WorkstationCapabilityProtocol/reference/wcpd
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest        # scopes, sandbox, audit chain, JWT, all adapters
.venv/bin/wcpd --help

Docker

The release workflow publishes a container image to GHCR (ghcr.io/kchemorion/wcpd) on each v* tag. It boots the headless profile (fs / exec / system and the other container-safe families) and is proven core-conformant in CI.

docker run --rm -i ghcr.io/kchemorion/wcpd:latest stdio   # once published
# or build locally:
docker build -t wcpd reference/wcpd && docker run --rm -i wcpd stdio

Running the server

wcpd stdio            # local single-user MCP over stdio (OS session = trust boundary; no JWT)
wcpd serve            # HTTP/MCP binding for networked/multi-tenant use (workstation-addressed JWT)
wcpd doctor           # probe which capability tiers are available on this host
wcpd token --help     # mint a scoped JWT for the HTTP binding

Restricted scopes are off by default and opt-in per flag (see Security):

wcpd stdio --allow-input --allow-osa --allow-browser-eval --allow-scheduler --allow-secrets

---

Connect it to Claude Desktop

1. Install wcpd into a venv outside any macOS TCC-protected folder (e.g. not under ~/Documents/, which sandboxed apps can't read):

   python3 -m venv ~/.wcp/venv
   ~/.wcp/venv/bin/pip install wcp            # or: pip install -e /path/to/reference/wcpd

2. Add a server entry to ~/Library/Application Support/Claude/claude_desktop_config.json (merge — don't clobber existing servers):

   {
     "mcpServers": {
       "wcp": {
         "command": "/Users/YOU/.wcp/venv/bin/wcpd",
         "args": ["stdio", "--allow-input", "--allow-osa"],
         "env": {
           "WCP_AUDIT_PATH": "/Users/YOU/.local/state/wcp/audit.jsonl",
           "WCP_WORKSTATION_ID": "my-mac"
         }
       }
     }
   }

3. Restart Claude Desktop (⌘Q, reopen) — the tool list only refreshes on launch.

4. macOS permissions: the perception/GUI families need TCC grants to the launching app. In System Settings → Privacy & Security, give Claude Desktop Accessibility (for ax/window), Screen Recording (for screen/window.capture), and Full Disk Access if you want it to reach protected folders. Ungranted ops honestly return WCP_BACKEND_UNAVAILABLE — WCP never bypasses TCC, SIP, or sudo.

Then ask Claude: "Using WCP, export my workstation as an RDF graph and tell me what you can do to it, grouped by domain."

---

Architecture

WCP is a wire-neutral core capability model plus bindings. The Model Context Protocol is the first normative binding, so every MCP-speaking agent works today.

• Operation registry is the single source of truth. The capability manifest (wcp.system.describe), the JSON schemas, and the MCP tool list are all pure projections of it — they can never drift (a CI gate enforces it).
• Ports and adapters: each family is a port Protocol + per-OS adapters (macOS/Linux/Windows) + a portable adapter where the CLI is identical cross-OS (git, containers, k8s). select_adapters picks the right set per host; GUI families are display-gated; the container profile drops hardware-bound families.
• Bindings: stdio for local single-user (the OS session is the trust boundary — no token); serve for networked/multi-tenant use with workstation-addressed JWTs.

See ADR-0002 (tiered action resolution + scoped control plane) and ADR-0003 (WCP as a standalone standard).

---

Security model

WCP is built to be powerful and safe enough to point at a real machine:

• Scoped least privilege. Every operation carries exactly one scope (wcp:<family>:<class>). A principal is granted a scope set; wildcards (*, wcp:fs:*) expand to normal scopes only.
• Five restricted scopes, never granted by wildcard, opt-in per flag: input:synthesize (--allow-input), osa:run (--allow-osa), browser:evaluate (--allow-browser-eval), scheduler:control (--allow-scheduler), security:secrets (--allow-secrets). Raw input, arbitrary automation/JS, persisted background triggers, and secret enumeration are all deliberate, revocable grants. This invariant is conformance-enforced.
• Sandbox confinement. Every filesystem-touching family (fs, search, camera, git, events) resolves user paths through one sandbox root and refuses to escape it. Destructive file ops soft-delete.
• Tamper-evident audit. Every invocation — including denials — appends to a hash-chained JSONL log; wcp.security.audit_verify re-walks the chain to prove it wasn't altered, and wcp.graph renders it as PROV-O provenance.
• No privilege escalation via composition. wcp.goal.execute runs multi-step plans by dispatching each sub-op through the same guarded, audited path — it can never do more than the caller's own scopes allow.
• Honest OS walls. WCP never bypasses SIP, TCC, or sudo; where a capability needs a permission or tool that isn't present, it returns WCP_BACKEND_UNAVAILABLE, never a fabricated success.
• Secrets are brokered. wcp.security.secrets_list returns keychain names/metadata only, never values; the JWT secret and audit payloads never surface through any read op.

Full model: spec/security.md.

---

Conformance

conformance/ is a standalone package (wcp-conformance) that certifies any WCP endpoint — the reference server or a third-party implementation — against the manifest schema, per-operation schemas, and the MCP binding. It reports a core_conformant verdict plus a pass/fail per family. The conformance suite is the executable definition of the standard.

pip install wcp-conformance     # (from source until first release tag)
wcp-conformance --endpoint http://localhost:8977/mcp \
  --jwt-secret "$WCP_JWT_SECRET" --workstation-id dev-ws --json report.json

See conformance/docs/certifying.md and SPEC.md § Conformance levels.

---

Repository layout

Path	Contents
SPEC.md, spec/	The normative specification (core model, security, families, bindings)
schemas/	Machine-readable JSON Schemas (manifest, per-operation params/results) — generated from the registry, drift-checked in CI
conformance/	Standalone conformance suite (wcp-conformance) — point it at any WCP endpoint
reference/wcpd/	wcpd, the reference server: ports-and-adapters over Linux, macOS, Windows, containers
docs/	ADRs, CI notes, design specs, and the parked v0.2 roadmap

---

Continuous integration

Every push to main and every PR runs: lint (ruff check + format), schema-drift (checked-in schemas/ must match the live registry), ci (unit tests + an end-to-end conformance run against a real wcpd, across Linux/macOS/Windows × Python 3.11/3.12), and container (the Docker image boots and is core-conformant headless). Pushing a v* tag runs release, which builds both packages and publishes them to PyPI (via trusted publishing) and a container image to GHCR. See docs/ci.md, including the one-time PyPI trusted-publisher setup before the first tag.

---

Roadmap

v0.1 is intentionally a complete, honest stopping point. The larger vision — a canonical Resource Model, transactions, an intent-contract layer, and a formal effect/capability substrate — is captured, and deliberately parked, in docs/vision/2026-07-03-wcp-v0.2-roadmap.md. Real usage of v0.1 drives what (if anything) graduates from it.

Contributing & license

See CONTRIBUTING.md. Licensed under Apache-2.0 — see LICENSE. Contributions are accepted under the same license (Apache-2.0 §5).