Optional off-page discovery layer, and how to read third-party WebMCP audits - #7
Merged
Conversation
…party audits references/discovery.md documents the pre-visit discovery conventions around WebMCP — the /.well-known/webmcp manifest, rel="webmcp" advertisement, llms.txt — and separates what the spec defines from what the surrounding ecosystem invented. Publishing is opt-in and approval-gated: a manifest is world-readable, so it mirrors only public unauthenticated tools and must be generated from the approved manifest with a drift test, never hand-maintained. The same guide gives HEAL and VERIFY a rule for third-party WebMCP checkers: their scores mix spec features with conventions and invented checks, so findings get classified and reported, never healed toward. No non-existent attributes, no forms added to an app that doesn't need them, no chasing browser-side APIs a page cannot provide. Ships templates/well-known-webmcp.json; version 0.4.0.
- document.modelContext is the specified surface; navigator.modelContext is the deprecated Chrome 149 compatibility fallback, and the table now says so - toolparamdescription belongs on the form control (or enclosing fieldset), not on the form element - the publication approval is persisted in pipeline.discovery (approved tool ids + created paths) before any file is written, so the gate survives a context reset and the audit can map the new hunks - the nginx snippet repeats the inherited security headers, because add_header in a location cancels every inherited one - a third-party finding that is a confirmed spec violation now means the harness is missing an assertion: add it, then heal — only conventions and invented checks stay report-only
…nheritance advice - pipeline.discovery gains paths-as-written plus a complete flag: approval alone could not distinguish 'approved, nothing published yet' from 'published', so a context reset mid-publication looked finished. Approved-but-incomplete is now explicitly unfinished work that blocks leaving INTEGRATE. - the no-baseline audit fallback collects pipeline.discovery.paths too, so published artifacts are audited rather than silently skipped - only a manifest this pipeline created or modified counts as an unmapped hunk; a pre-existing untouched one is reported, not flagged as our change - add_header_inherit merge (nginx 1.29.3+) inherits headers instead of cancelling them, so blindly repeating them duplicates CSP/HSTS — check the mode first, and diff the headers afterwards either way
TueJon
added
documentation
…ntract - integrate → verify now also requires pipeline.discovery to be null or complete; the transition table is what a literal agent follows, so the rule has to live there and not only in the prose - a discovery record written before the complete key existed reads as false: re-check the artifacts, then persist the flag — no migration required - an untouched pre-existing manifest is always reported, not only when it contradicts the integration: what it advertises is part of the app's agent surface either way - the Link-header guidance carries the same add_header_inherit caveat as the manifest location, instead of unconditionally telling the agent to repeat headers
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
WebMCP now has an ecosystem of checkers, inspector extensions and registries that grade
a page and hand the developer a score. Their lists mix three different kinds of item,
and an agent that treats the score as a to-do list will write markup that no
specification contains. This adds the missing guidance and the one piece of off-page
surface that is genuinely worth publishing.
references/discovery.md(new)Off-page discovery as an opt-in, approval-gated layer, never part of a default
integration:
document.modelContext; the declarative attributes, withtoolparamdescriptionon the control;toolactivated/toolcancel; the tool CSSpseudo-classes) versus deprecated (
navigator.modelContext, the Chrome 149compatibility surface) versus convention (
/.well-known/webmcp,rel="webmcp",llms.txt) versus invented (toolaction— it exists in no draft and no Chrome doc).pipeline.discoveryin.webmcpify/manifest.jsonholds the date, the exactpublishedToolssubset, thepathsappended as each artifact is written, and acompleteflag — so a contextreset mid-publication is distinguishable from a finished one, and AUDIT can map the
new hunks (including in the no-baseline fallback).
manifest, shipped with a drift test, regenerated with every contract change.
forever, so it lists only public, unauthenticated tools whose schemas any visitor
could already read in DevTools. Never auth-gated or admin tools, never unreleased
functionality.
application/json, HTTP 200 (a redirect counts as amiss), keep the repo file as
webmcp.jsonand map the extensionless path in theserver config. The nginx snippet distinguishes the default semantics (a location
add_headercancels inherited headers → repeat them) fromadd_header_inherit merge(nginx 1.29.3+, where repeating them duplicates CSP/HSTS), and says to diff the
headers afterwards either way.
Guard rails elsewhere
heal.md: heal failures, not scores. A third-party finding that is a confirmedspec violation means the harness is missing an assertion — add it, watch it fail,
heal it. Conventions and invented checks are report-only: no
toolaction, no formsadded to an app that doesn't need one, no chasing a browser-side
window.ai.verify.md: same classification before acting on any inspector finding.integrate.md: declarative tools need a form the app already has; otherwiseintegrate imperatively.
SKILL.md: the offer, the approval requirement, thepipeline.discoveryschema, andthe audit mapping.
templates/well-known-webmcp.json.Version 0.4.0 across the distribution manifests;
npm run checkgreen (17 tests). Thereference implementation of all three layers now runs on
webmcpify.at (TueJon/webmcpify.at#9).