Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,12 @@
## Decision Rules

- For normative behavior changes, update and approve the specification
repository before importing a new validator snapshot.
repository before importing a new validator selector.
- For validator behavior, use exact immutable selectors and add sibling
snapshots; never modify a published selector.
- Treat upstream specification tags and commits as informational provenance.
Validator package integrity is defined by its embedded schema, runtime, frozen
fixtures, package integrity, and immutable package release.
- A maintainer-approved additive tooling-metadata correction may modify a
published snapshot implementation only when schemas, conformance behavior,
diagnostics, and fixtures remain unchanged and the integrity exception is
Expand Down
19 changes: 10 additions & 9 deletions .github/skills/validator-snapshot-intake/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
name: validator-snapshot-intake
description:
Import an approved immutable MCP Description validator snapshot from the
specification repository. Use when adding a new draft or release-candidate
selector to @mcpdesc/validator.
Import reviewed MCP Description artifacts as an immutable validator selector.
Use when adding a new draft or release-candidate selector to
@mcpdesc/validator.
license: Apache-2.0
---

Expand All @@ -12,17 +12,18 @@ license: Apache-2.0
## Prerequisites

- Read the root and `packages/validator/AGENTS.md` files.
- Require an approved exact specification tag or full commit.
- Require an approved exact specification selector.
- Obtain a bundle with `manifest.json`, `runtime/`, and `fixtures/` from
`mcpdesc/mcpdesc-specification`.
- Confirm both repositories have clean worktrees before generation or import.

## Bundle Contract

The manifest uses `formatVersion: 1`, an exact prerelease `selector`, matching
`snapshotTag`, source repository and full commit, and a complete sorted-capable
`files` array. Every file entry contains a bundle-relative path under `runtime/`
or `fixtures/` and its lowercase SHA-256 digest.
`snapshotTag`, and a complete sorted-capable `files` array. Every file entry
contains a bundle-relative path under `runtime/` or `fixtures/` and its
lowercase SHA-256 digest. Source repository and commit metadata are optional and
informational.

## Workflow

Expand All @@ -32,8 +33,8 @@ or `fixtures/` and its lowercase SHA-256 digest.
npm run import:snapshot --workspace @mcpdesc/validator -- --check <bundle-directory>
```

2. Review the manifest, source commit, schema digest, semantic implementation,
and fixture corpus against the approved specification snapshot.
2. Review the manifest, schema digest, semantic implementation, and fixture
corpus against the approved specification artifacts.
3. Import only after approval:

```bash
Expand Down
10 changes: 7 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,10 @@ validation without creating a second source of normative specification text.
- Require exact immutable snapshot selectors.
- Do not infer a draft selector from `mcpdesc: "0.8.0"` alone.
- Do not change behavior captured for a published selector silently.
- Import a new snapshot only from an explicitly approved specification tag or
commit, with exact schema, semantic implementation, fixture, and digest
provenance. Never require a sibling specification checkout in routine CI.
- Import a new selector only from approved specification artifacts. Review and
freeze the exact schema, semantic implementation, and fixtures owned by the
validator package. Upstream tags and commits are informational provenance;
never require a sibling specification checkout in routine CI.
- Existing directories under `packages/validator/src/snapshots/` and
`packages/validator/test/snapshots/` are immutable. Add sibling selectors.
- A maintainer may approve an additive tooling-metadata correction to a
Expand All @@ -47,6 +48,9 @@ validation without creating a second source of normative specification text.
`snapshot-integrity.json` and the validator changelog.
- Keep npm versions, format versions, snapshot selectors, schema identities, and
MCP protocol revisions separate.
- Non-normative specification changelogs, FAQs, guides, governance, and release
prose may evolve without a validator or core release when package-owned
schema, behavior, and fixtures remain unchanged.

## New snapshot adoption

Expand Down
16 changes: 15 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,21 @@

All notable changes to this repository are documented here.

## [Unreleased]
## [0.9.0] - 2026-09-07

### Added

- Added MCP Description `0.8.0-rc.3` validator support and core support for
projection, merge, declaration selection, component reference resolution, and
migration from 0.7.0.
- Added RC.2 component reference resolution with deterministic terminal-target
provenance.

### Changed

- Snapshot integrity now protects package-owned selector bytes without binding
validation behavior to immutable specification repository documentation or
source commits.

## [0.8.1] - 2026-09-05

Expand Down
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,9 @@ dependencies must work in Node.js 22 and browser bundles.

Validator changes must preserve Node.js 20 support, deterministic offline
validation, and strict-CSP behavior. Never modify an existing published snapshot
directory. A later approved specification snapshot is added as a sibling with
exact source, schema digest, semantic, and fixture provenance.
directory. A later approved specification snapshot is added as a sibling with an
exact schema digest, reviewed semantic implementation, and frozen fixtures.
Upstream repository tags and commits are informational provenance.

Pull requests containing AI-assisted content must disclose the tool and extent
of assistance. Releases follow the maintainer-controlled process in
Expand Down
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,12 @@ The repository contains two independently versioned packages:
MCP Description snapshots, including strict-CSP browser entry points.

The package parses and serializes JSON or YAML source text, migrates validated
MCP Description 0.7.0 values to exact Draft 4, RC.1, or RC.2 snapshots with
stable conversion reports, projects and merges Effective Protocol Views through
RC.2, and selects declaration subsets by normative identity. Validator snapshots
provide the conformance authority for those operations. Published package
operations perform no network or file access and support browser bundlers.
MCP Description 0.7.0 values to exact Draft 4, RC.1, RC.2, or RC.3 snapshots
with stable conversion reports, projects and merges Effective Protocol Views
through RC.3, and selects declaration subsets by normative identity. Validator
snapshots provide the conformance authority for those operations. Published
package operations perform no network or file access and support browser
bundlers.

APIs remain experimental while MCP Description 0.8 is a community working draft.
npm package versions, MCP Description versions, immutable snapshot selectors,
Expand Down
6 changes: 4 additions & 2 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,10 @@ repository.
grounded in the RC.2 specification snapshot and conformance fixtures.
- [x] Add exact MCP Description RC.2 migration support from validated 0.7.0
documents.
- [x] Expose reusable-component resolution as a separate RC.1-only pure
operation with deterministic terminal-target provenance and existing
- [x] Adopt RC.3 with package-owned selector integrity and decouple
non-normative specification documentation from validator releases.
- [x] Expose reusable-component resolution as a separate RC.1, RC.2, and RC.3
pure operation with deterministic terminal-target provenance and existing
unresolved-reference diagnostics.
- Add normalization or comparison operations only where multiple consumers
demonstrate the same requirement.
Expand Down
6 changes: 3 additions & 3 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

75 changes: 41 additions & 34 deletions packages/core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,46 +66,53 @@ console.log(serializeMcpDescriptionMigrationReport(migrated.report));
```

Semantic operations require an exact immutable selector and support
`0.8.0-draft.4`, `0.8.0-rc.1`, and `0.8.0-rc.2`. They validate their source and
result with `@mcpdesc/validator`. Declaration selection uses MCP Description
identities: tool and prompt `name`, resource `uri`, and resource template
`uriTemplate`. It preserves all selected protocol-scoped variants and omits
empty declaration collections. Draft 4 constants and operations remain available
without being silently retargeted to RC.1.

| Operation | Draft 4 | RC.1 | RC.2 |
| ---------------------------------- | ------------- | --------- | -------------------------------------- |
| Effective Protocol View projection | Supported | Supported | Supported |
| Effective Protocol View merge | Supported | Supported | Supported |
| Declaration selection | Supported | Supported | Supported |
| Migration from 0.7.0 | Supported | Supported | Supported |
| Component reference resolution | Not supported | Supported | Pending provenance-compatible contract |

RC.2 projection preserves pre-standard server extension maps in every applicable
Effective Protocol View. `mergeEffectiveProtocolViews` combines compatible
views, retains semantically equivalent declarations across scopes, and rejects
conflicting views or unscoped metadata without mutating inputs.

Component reference resolution is RC.1-only. It validates before resolving,
returns a deep-cloned document with root component registries retained, and
reports deterministic provenance from each authored reference path to its
terminal component path. Intermediate chain hops are not exposed. The operation
uses the resolver exported through `@mcpdesc/validator/standalone`; this keeps
the snapshot-owned traversal authoritative while avoiding the runtime AJV entry
and a dependency cycle.
`0.8.0-draft.4`, `0.8.0-rc.1`, `0.8.0-rc.2`, and `0.8.0-rc.3`. They validate
their source and result with `@mcpdesc/validator`. Declaration selection uses
MCP Description identities: tool and prompt `name`, resource `uri`, and resource
template `uriTemplate`. It preserves all selected protocol-scoped variants and
omits empty declaration collections. Draft 4 constants and operations remain
available without being silently retargeted to RC.1.

| Operation | Draft 4 | RC.1 | RC.2 | RC.3 |
| ---------------------------------- | ------------- | --------- | --------- | --------- |
| Effective Protocol View projection | Supported | Supported | Supported | Supported |
| Effective Protocol View merge | Supported | Supported | Supported | Supported |
| Declaration selection | Supported | Supported | Supported | Supported |
| Migration from 0.7.0 | Supported | Supported | Supported | Supported |
| Component reference resolution | Not supported | Supported | Supported | Supported |

| Specification selector | First validator release | First core release |
| ---------------------- | ----------------------- | ------------------ |
| `0.8.0-rc.3` | `0.10.0` | `0.9.0` |
| `0.8.0-rc.2` | `0.9.0` | `0.8.0` |
| `0.8.0-rc.1` | `0.5.0` | `0.4.0` |
| `0.8.0-draft.4` | `0.4.0` | `0.1.0` |

RC.2 and RC.3 projection preserve pre-standard server extension maps in every
applicable Effective Protocol View. `mergeEffectiveProtocolViews` combines
compatible views, retains semantically equivalent declarations across scopes,
and rejects conflicting views or unscoped metadata without mutating inputs.

Component reference resolution supports RC.1, RC.2, and RC.3. It validates
before resolving, returns a deep-cloned document with root component registries
retained, and reports deterministic provenance from each authored reference path
to its terminal component path. Intermediate chain hops are not exposed. The
operation uses the resolver exported through `@mcpdesc/validator/standalone`;
this keeps the snapshot-owned traversal authoritative while avoiding the runtime
AJV entry and a dependency cycle.

Migration accepts a caller-validated MCP Description 0.7.0 value and validates
the result against the exact target snapshot. It moves the protocol revision to
root scope, wraps server capabilities, omits optional empty arrays, and converts
inline legacy security schemes to deterministic named definitions and
requirements. Generated names and deduplication are reported as warnings for
author review. RC.1 and RC.2 callers may opt into `defaultProtocolVersion` when
the source omits `info.protocolVersion`; the source value always takes
precedence, and no built-in default is applied. Every migration result includes
a stable, JSON-compatible report that distinguishes success, success with
warnings, and failure and records diagnostics, applied defaults, and proven
conversion changes. The package does not ship or duplicate the frozen 0.7.0
schema, so callers must validate that source before setting
author review. RC.1, RC.2, and RC.3 callers may opt into
`defaultProtocolVersion` when the source omits `info.protocolVersion`; the
source value always takes precedence, and no built-in default is applied. Every
migration result includes a stable, JSON-compatible report that distinguishes
success, success with warnings, and failure and records diagnostics, applied
defaults, and proven conversion changes. The package does not ship or duplicate
the frozen 0.7.0 schema, so callers must validate that source before setting
`sourceValidated: true`.

Source parsing accepts text and returns a JSON-compatible value or structured
Expand Down
4 changes: 2 additions & 2 deletions packages/core/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@mcpdesc/core",
"version": "0.8.1",
"version": "0.9.0",
"description": "Pure semantic operations for MCP Description documents",
"type": "module",
"license": "Apache-2.0",
Expand Down Expand Up @@ -50,7 +50,7 @@
"typecheck": "tsc --build --pretty false"
},
"dependencies": {
"@mcpdesc/validator": "0.9.0",
"@mcpdesc/validator": "0.10.0",
"jsonc-parser": "3.3.1",
"yaml": "2.9.0"
}
Expand Down
Loading
Loading