# Prior art and design lessons

**Status:** working notes, reviewed 2026-08-02.

This is a focused comparison, not a complete landscape and not a claim that Class Profiles is novel. The useful question is which existing ideas should constrain, simplify, or replace parts of the prototype.

## Model Context Protocol

The [MCP architecture](https://modelcontextprotocol.io/docs/learn/architecture) defines client/server communication, discovery, transports, and primitives such as tools, resources, and prompts. A server can list tools with server-provided names, descriptions, and schemas, and a client can call them.

Class Profiles does not replace that protocol. It explores an additional artifact for cases where independently implemented MCP tools are meant to represent the same capability class. The proposed agreement includes semantic identity, shared operations, optional facets, degradation, and behavioral fixtures.

**Lesson:** remain a layer over MCP and reuse its transport, discovery, and invocation mechanisms. Do not turn a profile into another general RPC protocol.

### Revision `2026-07-28`

The [`2026-07-28` revision](https://modelcontextprotocol.io/specification/2026-07-28) is the specific target of the current alignment. It removed the `initialize` handshake and protocol-level sessions, made capability negotiation per-request, added a mandatory `server/discover` RPC, moved asynchronous work into the Tasks extension, replaced server-initiated requests with the multi round-trip pattern, and removed stream resumability. Quoted evidence is recorded in [`research/mcp-spec/2026-07-28-capture.md`](research/mcp-spec/2026-07-28-capture.md); the resulting decisions are in [`decisions/0001`](decisions/0001-mcp-2026-07-28-alignment.md).

Two passages bear directly on whether this proposal has a problem to solve.

The revision **acknowledges the multi-server collision and offers a naming remedy**: aggregating clients "MAY encounter naming collisions (for example, two servers each exposing a `search` tool) and SHOULD implement a disambiguation strategy such as prefixing tool names with a server identifier" — while noting the server name itself is not guaranteed unique. Prefixing distinguishes *which server said it*, never *what it means*.

The revision also makes behavioral hints **normatively untrusted**: "clients MUST consider tool annotations to be untrusted unless they come from trusted servers."

**Lesson:** the gap Class Profiles addresses is now stated inside the protocol it layers on, and the conformance model in [`spec/03`](spec/03-conformance.md) is a candidate answer to the untrusted-annotation problem rather than an unmotivated addition. Where the revision standardizes something this prototype shimmed — asynchrony, change notification, capability probing — the shim migrates to it.

## W3C explainers and Web Share

The W3C TAG’s [Writing Effective Explainers](https://www.w3.org/TR/explainer-explainer/) treats an explainer as a living document for finding consensus. It recommends leading with the user-facing problem, proposed approach, practical use cases, alternatives, discussion venues, and relevant accessibility, internationalization, privacy, and security considerations. It also recommends short, skimmable prose and clear separation between current behavior and the proposed change.

The [Web Share explainer](https://github.com/w3c/web-share/blob/main/docs/explainer.md), which the TAG guidance lists as a good example, opens with a concrete user flow, then shows a small code example, current alternatives, and frequently asked questions. It keeps the adjacent “receive a share” problem in a separate proposal.

These documents are process and communication precedents, not competing tool protocols.

**Lesson:** lead with the problem and the open question, then a worked journey. Put status, non-goals, missing evidence, alternatives, and a discussion path in plain view. Keep adjacent ambitions out of the draft.

## Debug Adapter Protocol

The [Debug Adapter Protocol overview](https://microsoft.github.io/debug-adapter-protocol/overview.html) describes a high-level protocol between development tools and concrete debuggers. Existing debugger APIs are presented through intermediary debug adapters. During initialization, clients and adapters exchange capability flags; an absent flag means the feature is unsupported.

DAP standardizes a debugging wire protocol and interaction model. Class Profiles instead uses MCP as its wire protocol and proposes separate contracts for individual capability classes.

**Lesson:** adapters can make existing implementations first-class participants, and optional support needs explicit negotiation. A projection must not conceal missing behavior.

## OpenFeature

[OpenFeature](https://openfeature.dev/docs/reference/intro/) defines a shared feature-flag evaluation API. Its [provider interface](https://openfeature.dev/specification/sections/providers/) is the translation layer between application calls and a particular flag system; a provider may wrap a vendor SDK, call a service, or read local data.

The provider pattern resembles the prototype’s separation between a stable consumer-facing contract and backend-specific projection. The scope differs: OpenFeature specifies feature-flag evaluation through language SDKs, while Class Profiles is experimenting with artifact-defined, effectful tool behavior across capability classes.

**Lesson:** keep the consumer surface separate from backend mapping, make provider provenance visible, and specify errors and defaults instead of relying on a translator’s intuition.

## Standard Schema

[Standard Schema](https://standardschema.dev/) defines a deliberately small TypeScript interface that validation libraries can implement and tools can consume without a library-specific adapter. Implementations retain a vendor identifier while exposing a common versioned surface.

Standard Schema standardizes an in-process structural interface for typed validation. It does not attempt to define remote tool jobs, side effects, or behavioral equivalence.

**Lesson:** an interoperability surface can be small, producer-implemented, and versioned without erasing implementation identity. Class Profiles should justify every field beyond that minimum.

## CommonMark

The [CommonMark specification](https://spec.commonmark.org/) begins with concrete ambiguities that caused Markdown implementations to diverge. Its side-by-side Markdown and HTML examples are also executable conformance tests.

Markdown parsing is substantially more closed and deterministic than stateful Calendar operations. A Calendar fixture also needs setup, calls, observations, and rules for excluding backend-specific identity from comparison.

**Lesson:** disagreements become reviewable when examples double as tests. The fixture vocabulary should stay small, deterministic, and independent of one implementation.

## Consequences for this draft

These comparisons suggest a conservative path:

1. Use MCP rather than designing another transport or general tool protocol.
2. Keep the shared surface limited to one recognizable capability class and make extensions explicit.
3. Treat direct implementations and reviewed projections as different provenance, not different grades.
4. Make unsupported behavior and degradation observable.
5. Prefer executable cases over increasingly elaborate prose.
6. Ask for independent implementation evidence before discussing standardization.

An alternative or prior result that makes part of the prototype unnecessary is a successful research outcome. Please add it through the process in [CONTRIBUTING.md](CONTRIBUTING.md).