github/awesome-copilot / skills/webmcpify
webmcpify
VerifiedWebMCP agent skill for curated core coverage or route-by-route parity — inventory an existing web app, integrate approved tools, then inspect, verify and heal them in a real browser. Use for "webmcpify", "add WebMCP", or "expose app actions to AI agents".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 31.3 KB |
| references/discovery.md | markdown | 8.5 KB |
| references/heal.md | markdown | 8.3 KB |
| references/integrate.md | markdown | 10.7 KB |
| references/inventory.md | markdown | 9.9 KB |
| references/native-compatibility.md | markdown | 5.3 KB |
| references/reverify.md | markdown | 11.3 KB |
| references/runtime.md | markdown | 8.7 KB |
| references/security.md | markdown | 5.0 KB |
| references/verify.md | markdown | 15.4 KB |
| references/workbench.md | markdown | 5.0 KB |
| scripts/workbench.mjs | script | 5.6 KB |
| templates/mutation-journal.js | script | 22.3 KB |
| templates/mutation-journal.ts | script | 25.8 KB |
| templates/webmcp-compat.js | script | 2.5 KB |
| templates/webmcp-jsx.d.ts | script | 2.3 KB |
| templates/webmcp-workbench.js | script | 37.9 KB |
| templates/webmcp.d.ts | script | 6.1 KB |
| templates/webmcp.spec.ts | script | 18.9 KB |
| templates/webmcpify.js | script | 12.0 KB |
| templates/webmcpify.ts | script | 12.5 KB |
| templates/well-known-webmcp.json | config | 1.2 KB |
| tests/README.md | markdown | 1.3 KB |
| tests/workbench-cli.test.mjs | script | 4.5 KB |
| tests/workbench.test.mjs | script | 5.4 KB |
references/reverify.md
View on GitHub# Re-verification after an app or environment change
Read this on resume, an explicit `verify`, or a release check of an existing
integration. A successful run proves the recorded app and environment, not every
future release. This is evidence maintenance; it does not authorize deployment,
new tools, production effects, or renewed execution of an uncertain mutation.
## Record the inputs to a successful check
After each tool passes native verification, store `verifiedAgainst` on its
manifest entry (an optional Manifest v4 field; absent means unknown):
```json
{
"at": "2026-09-14T12:00:00Z",
"contractRevision": 1,
"appRevision": "git-sha-or-build-id",
"files": {"src/webmcp/tools.ts": "sha256:..."},
"environment": {
"origin": "https://app.example.test",
"browser": "Chrome 150.0.7871.186",
"harness": "playwright-page-context",
"inputMode": "json-string",
"roles": ["member"],
"fixtureRevision": "seed-v2"
},
"evidence": "local-redacted-report-path"
}
```
`files` covers the tool implementation, shared runtime, generated harness and
compat helper, plus handlers/routes/stores and dependency lockfiles relevant to
its behavior. Hash current working-file contents, including approved uncommitted
edits: HEAD alone misses a changed working tree. Store hashes and fixture ids,
never credentials or fixture data. Record actual flags and native/simulated mode
in the linked report; only native evidence can produce this record. Use null for
an unavailable app/build revision; without a usable file map treat reuse as
unproven. A backend build/config change relevant to the UI path also invalidates
the evidence even when frontend files did not change.
## Durable mutation execution journal
Manifest v4 adds `mutationExecutions: []` on each tool. This is a required
workflow journal for new mutation runs, not a browser API or an automatic feature
of the vendored runtime. Vendor `templates/mutation-journal.{ts,js}` next to the
spec and use its Node/host-side `openMutationJournal`, `beforeDispatch`, `settle`
and `close` operations; a browser-only callback is not durable. The helper prefers
`flock(1)`, falls back to macOS/FreeBSD `lockf(1)` descriptor mode (which implies
`-k`), and fails closed when neither advisory-lock command is available. Other
runners must adapt dispatch through these same hooks rather than reproduce the
locking and durability protocol.
The helper opens the sidecar once without following symlinks, rejects non-regular
or multiply linked files, and passes that verified descriptor to the lock backend.
The short acquisition process exits while the runner retains the locked open-file
description itself, so there is no separately killable holder between a journal
write and dispatch. A competing descriptor verifies that the kernel lock survived
acquisition; device/inode checks at every durable I/O boundary fence pathname
replacement. Existing journals are validated in full before use; only an actually
absent `mutationExecutions` field is migrated, while malformed entries, duplicate
execution IDs and invalid cleanup-parent links fail closed without a rewrite.
On its first execution-capable open it also records one stable
`mutationLockIdentity` in the manifest and sidecar metadata; a missing or different
sidecar identity thereafter cannot become a second operational lock.
Each entry has `executionId`, `tool`, `contractRevision`, `origin`, `role`,
`fixtureRevision`, `argumentsFingerprint` (SHA-256 of canonical JSON with sorted
object keys), `startedAt`, `state` (`started` or `reconciled`), and local redacted
`evidence`. Do not store raw secrets or arguments; keep sensitive fingerprints
local. Use a new executionId for every authorized invocation, including invalid
examples and cleanup actions that can mutate. Fingerprints identify attempts;
they are not a server idempotency guarantee.
1. Before any execution-capable runner scans or reads the manifest, open/create the
canonical `.webmcpify/manifest.lock` sidecar without replacing it and acquire a
blocking exclusive OS advisory lock on that file. Every runner for the target
repo must resolve the same canonical path. Hold the same locked file descriptor
through recovery, dispatch, reconciliation, settlement and the final manifest
directory fsync. Atomic replacement of `manifest.json` must never change the
lock identity. A bounded waiter may stop, but it must not read, write, reconcile
or dispatch before ownership is acquired.
2. The successful OS-lock acquisition is the single atomic ownership transition.
After acquiring it, write and fsync diagnostic owner metadata into the still-locked
sidecar (random owner token, host, PID and process
start identity); never use that metadata, a PID probe, age or heartbeat as
permission to steal. Process death releases the kernel lock, so a successor may
overwrite stale metadata only **after** it acquires the same sidecar lock. Never
unlink, rename or recreate the sidecar during acquisition or recovery: that would
create a second lock identity and could bypass a live holder. If the platform or
filesystem cannot provide this invariant, mutation execution fails closed.
3. Once ownership is acquired, scan **all tools**, regardless of terminal status,
for `started` entries. Acquisition serializes this scan with every journal write;
never inspect the manifest before the lock and then overwrite its journal.
4. Reconcile unresolved entries through an independent authoritative read path
using their original role/fixture/argument identity. Resolve required cleanup
too. Unknown outcome or unverified cleanup blocks further mutation dispatch,
even with different arguments. Retain every started entry during stale-owner
recovery.
5. Before each mutation dispatch, under the lock append a `started` entry and
durably replace the manifest (write a sibling temporary file, fsync it,
atomic rename, fsync the directory). Verify the stored entry before calling
the tool. Persistence failure means **do not dispatch**. Hold ownership through
reconciliation; concurrent sessions must not race this protocol.
6. After execution, independently establish the effect or proven absence of an
effect, verify the expected/unchanged records and complete required cleanup.
Only then atomically mark `reconciled` with outcome, timestamp and evidence.
Keep the entry for audit; `verified` is a separate verdict requiring all checks.
Timeouts, cancellation, exception, failed cleanup or process death leave
`started` intact. Never clear it on an error handler or status reset.
7. Cleanup that mutates needs its own pre-dispatch entry linked by
`parentExecutionId`. During recovery only the specifically reconciled cleanup
action may bypass the unresolved-parent gate; uncertain cleanup itself must
be read/reconciled before retry. Do not recursively schedule cleanup of cleanup.
Before releasing ownership, durably settle every completed entry, fsync the
manifest directory, optionally record `releasedAt` in the locked sidecar, then
unlock/close it. A crash needs no sidecar deletion: the kernel releases ownership
while the durable `started` entry remains for the next holder to reconcile.
Apply this to VERIFY, HEAL retries, Playwright/Puppeteer harnesses and smoke/model
evals. Workbench blocks mutations entirely; its read-only invocations do not
implement or replace this protocol. Disable runner-level retries and
wrap **every** dispatch, including model-selected calls, with the journal hooks.
If an external runner cannot expose those hooks, expose only read-only tools or
mark mutation evals not-run; pre-recording an entire eval is insufficient.
`status` remains read-only and reports unresolved entries without reconciling.
Migration: a missing array means historical evidence is unknown, **not** an
in-flight call. On the next execution-capable resume, initialize it to `[]`,
clear historical `verifiedAgainst`, and reset formerly verified tools to
`integrated` for fresh checks within the approved scope. Do not invent started
records for old completed runs. If the operator or logs establish an actual
interrupted legacy mutation, record it as unresolved and reconcile before replay.
Never erase existing journal entries during migration or contract invalidation.
## Resume with bounded invalidation
1. `status` reads and reports counts plus evidence age/unknowns; it never starts a
browser, changes statuses or executes tools. `inventory` remains inventory-only.
2. In `full` or `verify`, compare recorded contracts, relevant files and the test
environment. Unchanged inputs retain their evidence. An explicit `verify`
still runs the selected integrated/verified tools as requested.
3. Changed implementation or environment: reset affected `verified` tools to
`integrated`, preserve their previous evidence in the report, clear the stale
`verifiedAgainst`, log the reason and return a completed pipeline to `verify`.
Shared runtime/harness changes affect all dependent tools. If dependencies or
provenance are unknown, re-verify all integrated/verified tools in the approved
scope. Do not rescan unaffected inventory or overwrite baseline-dirty files.
4. Changed contract, role/origin authorization, or mutation scope: return affected
tools to the human gate. Existing approval remains valid only for the same
approved contract and test effects. Never silently approve a new origin.
5. Interrupted mutation with uncertain outcome: inspect through the UI's read
path and reconcile disposable data/cleanup before another execution. If the
outcome cannot be established, record a blocker; do not replay it on resume.
6. Keep rejected/skipped tools and their reasons. Reconsider them only when a
recorded blocking condition changes or the user changes scope; return changed
contracts to the gate. Never count skipped tools as verified coverage.
Run the usual deterministic assertions and cleanup. Re-run selection/journey
evals when names, descriptions, available tool sets or critical workflows change;
record model/backend/version and repeated-run outcomes separately from native
contract evidence. Runtime verification alone does not prove model selection or
that another client supports the same surface.
Source boundaries checked 2026-09-14: [Chrome WebMCP](https://developer.chrome.com/docs/ai/webmcp)
is experimental; [Chrome execution](https://developer.chrome.com/docs/ai/webmcp/imperative-api)
and [Puppeteer](https://pptr.dev/guides/webmcp) have different version requirements.
The invalidation procedure above is webmcpify policy, not a WebMCP spec feature.
## Unsupported host and Workbench fallback
Windows without `flock(1)` or `lockf(1)` cannot run this shipped mutation journal;
it fails closed. Do not bypass locking, substitute an in-memory/browser lock, or
install dependencies without user approval. Continue only read-only inventory and
checks and report mutation checks **not-run** until a supported host journal
runner is available. Do not count them as verified.
Workbench is always read-only, in Native and Simulated transport: only observed,
non-excluded approved manifest tools with `mutating: false` may run. Simulated
transport still calls application handlers and does not make them side-effect-free.
Use the host journal runner for every mutation, including invalid examples and
cleanup; Workbench cannot supply those hooks. See [workbench.md](workbench.md) for
separate Playwright package and browser download consent requirements.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |