From 320e5eed462663448ddfd4ad7cca1431991d4bb3 Mon Sep 17 00:00:00 2001 From: Kiptengwer Date: Fri, 3 Jul 2026 03:47:35 +0200 Subject: [PATCH 1/2] docs: rewrite README for the full 35-family/258-op surface - Replace the stale ~7-family description with the complete Level-5 catalog (35 families / 258 ops), grouped by domain, incl. the wcp.graph capstone. - Add real installation instructions: PyPI (wcpd + extras), from source, Docker/GHCR, running the server, and a full Claude Desktop wiring guide with the ~/.wcp-outside-TCC pattern and macOS permission notes. - Document the security model (5 restricted opt-in scopes, sandbox, audit, no-escalation, honest OS walls), architecture, conformance, and the parked v0.2 roadmap. - Flag the missing LICENSE as a release prerequisite. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 256 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 172 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index c8b78a5..a3859a6 100644 --- a/README.md +++ b/README.md @@ -2,115 +2,203 @@ [![ci](https://github.com/kchemorion/WorkstationCapabilityProtocol/actions/workflows/ci.yml/badge.svg)](https://github.com/kchemorion/WorkstationCapabilityProtocol/actions/workflows/ci.yml) [![lint](https://github.com/kchemorion/WorkstationCapabilityProtocol/actions/workflows/lint.yml/badge.svg)](https://github.com/kchemorion/WorkstationCapabilityProtocol/actions/workflows/lint.yml) +[![schema-drift](https://github.com/kchemorion/WorkstationCapabilityProtocol/actions/workflows/schema-drift.yml/badge.svg)](https://github.com/kchemorion/WorkstationCapabilityProtocol/actions/workflows/schema-drift.yml) -**Status: v0.1 draft — under active design. Not yet stable.** - -**Use it now:** operate your computer through WCP + any MCP-speaking AI -(Claude Code, Claude Desktop, ...) in 60 seconds — -see [`QUICKSTART.md`](QUICKSTART.md). - -WCP is an open, vendor-neutral standard for how AI agents (and any -automation client) operate desktop operating systems. It defines a -unified, versioned, self-describing set of workstation capabilities — -files, command execution, windows, screen, input, applications, -clipboard — that Windows, Linux, macOS, and container environments -expose behind least-privilege scopes and tamper-evident audit logging. - -Instead of every agent framework reinventing brittle screen-scraping, -a WCP server lets a client: - -1. **Discover** what this workstation can actually do - (`wcp.system.describe` returns a versioned capability manifest, - including live backend health). -2. **Act** through the most structured interface available — native - APIs first, raw input synthesis strictly last, and only when the - `wcp:input:synthesize` scope has been granted *verbatim* (no - wildcard, not even `*`, can grant it). -3. **Be audited** — every invocation, including denials, lands in a - hash-chained tamper-evident log. - -WCP is layered as a wire-neutral **core capability model** plus -**bindings**; the [Model Context Protocol](https://modelcontextprotocol.io) -is the first normative binding, so every MCP-speaking agent can use a -WCP workstation today. +**An open, vendor-neutral standard for how AI agents discover, understand, and operate a whole workstation — under governed, audited, revocable authority.** -## Repository layout +**Status: v0.1 — reference implementation complete, conformance-gated, cross-OS CI green. The spec is a draft and may still change.** -| Path | Contents | +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`](QUICKSTART.md). **The normative spec** → [`SPEC.md`](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) | |---|---| -| `SPEC.md`, `spec/` | The normative specification (core model, security, families, bindings) | -| `schemas/` | Machine-readable JSON Schemas (manifest, per-operation params/results) | -| `conformance/` | Standalone conformance suite — point it at any endpoint claiming WCP | -| `reference/wcpd/` | `wcpd`, the reference server: ports-and-adapters over Linux, macOS, Windows, containers | -| `docs/adr/` | Architecture decision records | +| **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`](SPEC.md) and [`spec/`](spec/); machine-readable schemas are in [`schemas/`](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. -## Design documents +--- -- [Design spec (2026-07-02)](docs/superpowers/specs/2026-07-02-wcp-standard-design.md) -- [ADR-0003: WCP is a standalone open standard](docs/adr/0003-wcp-standalone-standard.md) -- [ADR-0002: tiered action resolution & scoped control plane](docs/adr/0002-agent-control-plane.md) +## Installation -## The specification +WCP ships two Python packages (both target **Python ≥ 3.10**, and both run on Linux, macOS, and Windows): -The normative standard lives in [`SPEC.md`](SPEC.md) and [`spec/`](spec/): -the [core capability model](spec/core.md), the [security model](spec/security.md), -and the [MCP binding](spec/bindings/mcp.md). Third parties implement from these. +- **`wcpd`** — the reference server (the thing you run and connect an AI to). +- **`wcp-conformance`** — the standalone test suite that certifies *any* WCP endpoint. -## Reference implementation quickstart +### 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). ```bash -cd reference/wcpd +pip install wcpd # the reference server +pip install "wcpd[graph]" # + live SPARQL (rdflib) for wcp.graph.export +wcpd --help +``` + +Optional extras: + +| Extra | Enables | +|---|---| +| `wcpd[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. | +| `wcpd[linux-ax]` | The pip half (`PyGObject`) of the Linux accessibility backend. `pyatspi` itself comes from your OS package manager (`python3-pyatspi` / `at-spi2-core`). | +| `wcpd[windows-ax]` | The COM binding (`comtypes`) for the Windows UI Automation accessibility backend. | + +### From source + +```bash +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 +.venv/bin/python -m pytest # scopes, sandbox, audit chain, JWT, all adapters +.venv/bin/wcpd --help ``` -Discover a workstation's capabilities — `wcp.system.describe` returns the -versioned manifest (a projection of the operation registry): +### Docker -```python -from wcpd.server import build_registry -from wcpd.core.manifest import build_manifest +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. -manifest = build_manifest(build_registry()) -print(manifest["protocolVersion"]) # "0.1.0" -print(sorted(manifest["families"])) # ['wcp.exec', 'wcp.fs', 'wcp.input', ...] +```bash +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 ``` -Over MCP this is the tool `wcp_system_describe` (see the -[naming rule](spec/bindings/mcp.md#tool-naming)); the `tools/list` surface -always agrees with the manifest. +### Running the server + +```bash +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](#security-model)): + +```bash +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): + + ```bash + python3 -m venv ~/.wcp/venv + ~/.wcp/venv/bin/pip install wcpd # 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): + + ```json + { + "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](https://modelcontextprotocol.io) 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](docs/adr/0002-agent-control-plane.md) (tiered action resolution + scoped control plane) and [ADR-0003](docs/adr/0003-wcp-standalone-standard.md) (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::`). 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`](spec/security.md). + +--- ## Conformance -[`conformance/`](conformance/) is a standalone conformance test suite — -its own pip package, independent of `reference/wcpd` — that certifies -**any** WCP endpoint (the reference server or a third-party -implementation) against the published manifest schema, per-operation -schemas, and MCP binding. It reports a `core_conformant` verdict plus a -pass/fail per capability family. The reference server, `wcpd`, is proven -core-conformant by this suite. +[`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. ```bash -wcp-conformance --endpoint http://localhost:8977/mcp --jwt-secret $WCP_JWT_SECRET --workstation-id dev-ws --json report.json +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`](conformance/docs/certifying.md) -for the full guide (both token modes, read-only-by-default, and how to -read the report), and [`SPEC.md` § "Conformance levels"](SPEC.md#conformance-levels) -for what a conformance claim must state. +See [`conformance/docs/certifying.md`](conformance/docs/certifying.md) and [`SPEC.md` § Conformance levels](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](docs/vision/2026-07-03-wcp-v0.2-roadmap.md) | + +--- ## Continuous integration -Every push to `main` and every pull request runs four gates: `lint` -(ruff check + format), `schema-drift` (the checked-in `schemas/` must -match the live operation registry), `ci` (unit tests + an end-to-end -conformance run against a real `wcpd`, across Linux/macOS/Windows and -Python 3.11/3.12), and `container` (the shipped Dockerfile boots and is -core-conformant for the headless `fs`/`exec`/`system` families). Pushing -a `v*` tag runs `release`, which builds both packages and publishes them -to PyPI (via trusted publishing) and GHCR. - -See [`docs/ci.md`](docs/ci.md) for what each workflow asserts, where its -artifacts land, and the exact commands to reproduce every check locally -— including the one-time PyPI trusted-publisher setup required before the -first release tag. +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`](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`](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`](CONTRIBUTING.md). **A `LICENSE` file has not yet been added** — until one is, default copyright applies. An open standard needs an explicit license (Apache-2.0 or MIT are the usual choices for a spec + reference implementation); adding one is a prerequisite for the first public release. From 01af236e362013db872952d4c15254a72de8c0e4 Mon Sep 17 00:00:00 2001 From: Kiptengwer Date: Fri, 3 Jul 2026 03:53:48 +0200 Subject: [PATCH 2/2] chore(release): add Apache-2.0 LICENSE + PyPI packaging metadata - Add Apache-2.0 LICENSE at repo root and in each package dir (so wheels/ sdists bundle it via setuptools' default license-files glob). - Fill pyproject metadata for wcpd and wcp-conformance: readme (long description), license, authors, keywords, classifiers (OSI license, OS, Python 3.10-3.12), and [project.urls]. - Rewrite reference/wcpd/README.md as the package's PyPI front page (accurate 35-family surface, install/run/security, Claude Desktop pointer). - Update root README license section to Apache-2.0. Verified: python -m build produces clean sdists+wheels for both packages; METADATA carries License/classifier/Project-URL/markdown description and the bundled LICENSE. Names 'wcpd' and 'wcp-conformance' are unclaimed on PyPI. Co-Authored-By: Claude Opus 4.8 (1M context) --- LICENSE | 201 ++++++++++++++++++++++++++++++++++ README.md | 2 +- conformance/LICENSE | 201 ++++++++++++++++++++++++++++++++++ conformance/pyproject.toml | 28 +++++ reference/wcpd/LICENSE | 201 ++++++++++++++++++++++++++++++++++ reference/wcpd/README.md | 67 +++++------- reference/wcpd/pyproject.toml | 33 ++++++ 7 files changed, 690 insertions(+), 43 deletions(-) create mode 100644 LICENSE create mode 100644 conformance/LICENSE create mode 100644 reference/wcpd/LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9e61ec9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or Derivative + Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 The Workstation Capability Protocol contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index a3859a6..dacf957 100644 --- a/README.md +++ b/README.md @@ -201,4 +201,4 @@ v0.1 is intentionally a complete, honest stopping point. The larger vision — a ## Contributing & license -See [`CONTRIBUTING.md`](CONTRIBUTING.md). **A `LICENSE` file has not yet been added** — until one is, default copyright applies. An open standard needs an explicit license (Apache-2.0 or MIT are the usual choices for a spec + reference implementation); adding one is a prerequisite for the first public release. +See [`CONTRIBUTING.md`](CONTRIBUTING.md). Licensed under **Apache-2.0** — see [`LICENSE`](LICENSE). Contributions are accepted under the same license (Apache-2.0 §5). diff --git a/conformance/LICENSE b/conformance/LICENSE new file mode 100644 index 0000000..9e61ec9 --- /dev/null +++ b/conformance/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or Derivative + Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 The Workstation Capability Protocol contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/conformance/pyproject.toml b/conformance/pyproject.toml index ef7849c..c19a16a 100644 --- a/conformance/pyproject.toml +++ b/conformance/pyproject.toml @@ -2,9 +2,37 @@ name = "wcp-conformance" version = "0.1.0" description = "Conformance test suite for the Workstation Capability Protocol (WCP)" +readme = "README.md" +license = { text = "Apache-2.0" } +authors = [{ name = "The Workstation Capability Protocol contributors" }] +keywords = [ + "mcp", + "model-context-protocol", + "conformance", + "wcp", + "workstation", + "standard", +] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "License :: OSI Approved :: Apache Software License", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Software Development :: Testing", +] requires-python = ">=3.10" dependencies = ["mcp>=1.2", "httpx>=0.27", "jsonschema>=4.21", "pyjwt>=2.8"] +[project.urls] +Homepage = "https://github.com/kchemorion/WorkstationCapabilityProtocol" +Repository = "https://github.com/kchemorion/WorkstationCapabilityProtocol" +Documentation = "https://github.com/kchemorion/WorkstationCapabilityProtocol/blob/main/SPEC.md" +Issues = "https://github.com/kchemorion/WorkstationCapabilityProtocol/issues" + [project.optional-dependencies] dev = ["pytest>=8", "pytest-asyncio>=0.23"] diff --git a/reference/wcpd/LICENSE b/reference/wcpd/LICENSE new file mode 100644 index 0000000..9e61ec9 --- /dev/null +++ b/reference/wcpd/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or Derivative + Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 The Workstation Capability Protocol contributors + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/reference/wcpd/README.md b/reference/wcpd/README.md index 8fc056c..ba8681c 100644 --- a/reference/wcpd/README.md +++ b/reference/wcpd/README.md @@ -1,57 +1,40 @@ -# wcpd — WCP reference server +# wcpd — Workstation Capability Protocol (reference server) -The single control surface on a workstation running the Workstation -Capability Protocol (WCP). Exposes every desktop capability as a scoped, -audited MCP tool. The built-in AI Desktop Agent and any third-party agent -framework are both MCP clients of this server — there is no privileged -side channel. +`wcpd` is the reference implementation of the **Workstation Capability Protocol (WCP)** — an open, vendor-neutral standard that lets an AI agent discover, understand, and operate a whole workstation under governed, audited, revocable authority. -## Action tiers +It exposes **35 capability families / 258 operations** — accessibility tree, windows, screen, files, processes, packages, services, containers, VMs, Kubernetes, git, networking, a browser (Chrome DevTools), and an RDF/PROV-O knowledge-graph view of the machine — behind least-privilege scopes, sandbox confinement, and a hash-chained tamper-evident audit log. It speaks the [Model Context Protocol](https://modelcontextprotocol.io), so any MCP client (Claude Desktop, Claude Code, …) can use it today. -Actions resolve most-structured-first (see `docs/adr/0002`): +## Install -1. Native/app APIs (D-Bus, Docker, Git) — deterministic -2. CLI — deterministic where no API exists -3. Accessibility tree (AT-SPI2 / UIA) -4. Browser protocol (Playwright / CDP) -5. Input synthesis + vision — last resort, separately scoped - -## Scopes - -| Scope | Grants | -|---|---| -| `fs:read`, `fs:write` | Sandboxed filesystem (soft-delete to trash) | -| `terminal:exec` | One-shot commands and persistent PTY sessions | -| `window:control` | List/activate windows | -| `screen:capture` | Screenshots for vision models | -| `browser:control` | Browser automation | -| `apps:launch`, `apps:install` | Application lifecycle | -| `clipboard:rw` | Clipboard access | -| `input:synthesize` | **Tier 5** raw pointer/keyboard. Never granted by `fs:*` or any wildcard. | +```bash +pip install wcpd +pip install "wcpd[graph]" # + live SPARQL (rdflib) for wcp.graph.export +``` -Tokens are short-lived, workstation-addressed JWTs minted by the cluster -MCP gateway after OAuth 2.1. This server only verifies them. +Extras: `graph` (rdflib for live SPARQL), `linux-ax` (PyGObject for the Linux AT-SPI2 accessibility backend), `windows-ax` (comtypes for the Windows UI Automation backend). ## Run ```bash -export WCP_JWT_SECRET=... WCP_WORKSTATION_ID=ws-123 WCP_TENANT_ID=acme -export WCP_SANDBOX_ROOT=/home/user WCP_AUDIT_PATH=/var/log/wcp/audit.jsonl -uvicorn wcpd.server:build_app --factory --host 0.0.0.0 --port 8977 +wcpd stdio # local single-user MCP over stdio (OS session = trust boundary) +wcpd serve # HTTP/MCP binding (workstation-addressed JWT) for networked use +wcpd doctor # probe which capability tiers this host supports ``` -Every request needs `Authorization: Bearer `; unauthenticated -requests get 401. +Restricted scopes are off by default and opt-in per flag: +`--allow-input --allow-osa --allow-browser-eval --allow-scheduler --allow-secrets`. -## Test +## Security -```bash -pip install pyjwt pytest pytest-asyncio -python -m pytest -q # 20 tests: scopes, sandbox, audit chain, JWT, tools -``` +Every operation carries exactly one scope (`wcp::`); five restricted scopes (`input:synthesize`, `osa:run`, `browser:evaluate`, `scheduler:control`, `security:secrets`) are never granted by wildcard and are opt-in per flag. Filesystem-touching families are sandbox-confined; every invocation (including denials) is appended to a SHA-256 hash-chained audit log that `wcp.security.audit_verify` can re-check for tampering. WCP never bypasses SIP/TCC/sudo — where a capability isn't available it returns `WCP_BACKEND_UNAVAILABLE` rather than faking a result. + +## Connect to Claude Desktop + +Install into a venv outside macOS TCC-protected folders, add a `wcp` entry to +`~/Library/Application Support/Claude/claude_desktop_config.json`, restart Claude Desktop, +and grant Accessibility + Screen Recording. Full guide, complete capability catalog, and +the normative spec: **https://github.com/kchemorion/WorkstationCapabilityProtocol** -## Audit +## License -Every tool call (ok/denied/error) is appended to a SHA-256 hash-chained -JSON-lines log. `AuditLog.verify()` detects truncation or edits. A sidecar -ships the log to WORM object storage in production. +Apache-2.0. See [`LICENSE`](LICENSE). diff --git a/reference/wcpd/pyproject.toml b/reference/wcpd/pyproject.toml index c0b3642..107af5f 100644 --- a/reference/wcpd/pyproject.toml +++ b/reference/wcpd/pyproject.toml @@ -2,9 +2,42 @@ name = "wcpd" version = "0.1.0" description = "wcpd: reference implementation of the Workstation Capability Protocol (WCP)" +readme = "README.md" +license = { text = "Apache-2.0" } +authors = [{ name = "The Workstation Capability Protocol contributors" }] +keywords = [ + "mcp", + "model-context-protocol", + "ai-agents", + "automation", + "desktop-automation", + "accessibility", + "workstation", + "wcp", +] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "License :: OSI Approved :: Apache Software License", + "Operating System :: MacOS", + "Operating System :: POSIX :: Linux", + "Operating System :: Microsoft :: Windows", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Software Development :: Libraries", + "Topic :: System :: Systems Administration", +] requires-python = ">=3.10" dependencies = ["pyjwt>=2.8", "mcp>=1.2", "uvicorn>=0.30", "jsonschema>=4.21"] +[project.urls] +Homepage = "https://github.com/kchemorion/WorkstationCapabilityProtocol" +Repository = "https://github.com/kchemorion/WorkstationCapabilityProtocol" +Documentation = "https://github.com/kchemorion/WorkstationCapabilityProtocol/blob/main/SPEC.md" +Issues = "https://github.com/kchemorion/WorkstationCapabilityProtocol/issues" + [project.optional-dependencies] dev = ["pytest>=8", "pytest-asyncio>=0.23", "jsonschema>=4.21"] # wcp.ax on Linux (wcpd.adapters.linux.ax) is backed by AT-SPI2 via `pyatspi`,