@mcpdesc/validator 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -6,7 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Dates for published releases are the UTC publication dates recorded by npm.
 
-## [Unreleased]
+## [0.10.0] - 2026-09-07
+
+### Added
+
+- Added the immutable `0.8.0-rc.3` selector with behavior equivalent to RC.2,
+	its RC.3 schema identity, and frozen fixtures.
+- Added component reference resolution for RC.2 and RC.3 with deterministic
+	terminal-target provenance.
+
+### Changed
+
+- Validator integrity now relies on package-owned schema, runtime, fixture, and
+	package bytes. Specification repository tags and commits are retained only as
+	informational provenance.
+- Recorded maintainer-approved additive provenance corrections to the RC.2 and
+	RC.3 snapshot implementations. Their schemas, conformance results,
+	diagnostics, and frozen fixtures remain unchanged.
 
 ## [0.9.0] - 2026-09-04
 

package/README.md

@@ -44,16 +44,21 @@ a later draft is published.
 
 ## Supported snapshots
 
-Version `0.8.0` supports these immutable snapshots, newest first:
+The current workspace supports these immutable selectors, newest first:
 
-| Selector | Tag | Embedded schema SHA-256 |
+| Selector | First validator release | Embedded schema SHA-256 |
 |---|---|---|
-| `0.8.0-rc.2` | `v0.8.0-rc.2` | `40f6775dde052224114e91d6aa484d826eecf56b77f7ac87b4cf707ffbcb6ce8` |
-| `0.8.0-rc.1` | `v0.8.0-rc.1` | `936a0f24ade501fcabf3d6498c0440c445daa672a575573a35954cee49430ac4` |
-| `0.8.0-draft.4` | `v0.8.0-draft.4` | `93ed03f74059b5b3ce7509a96b59161bdab2c3cf7734397a9bec5a7588d0b03b` |
-| `0.8.0-draft.3` | `v0.8.0-draft.3` | `8823c1f1946360b2a44d00920e2092e5e4acd139a1964befad4eb0bf3ce96002` |
-| `0.8.0-draft.2` | `v0.8.0-draft.2` | `ab692c1a5a0f7e5f29be1940aa8c64a56d4620be0a19d00cf0a64680b7e517fa` |
-| `0.8.0-draft.1` | `v0.8.0-draft.1` | `4ceb6042c3fd31703199cd3db869ec5c35c17d2fe9ab7b2f5b96a2a3af0cebe4` |
+| `0.8.0-rc.3` | `0.10.0` | `a9c3ff77ba37c72362909f538f6e957d055e6fdb372f8b3d529e3651af3fecf4` |
+| `0.8.0-rc.2` | `0.9.0` | `40f6775dde052224114e91d6aa484d826eecf56b77f7ac87b4cf707ffbcb6ce8` |
+| `0.8.0-rc.1` | `0.5.0` | `936a0f24ade501fcabf3d6498c0440c445daa672a575573a35954cee49430ac4` |
+| `0.8.0-draft.4` | `0.4.0` | `93ed03f74059b5b3ce7509a96b59161bdab2c3cf7734397a9bec5a7588d0b03b` |
+| `0.8.0-draft.3` | `0.3.0` | `8823c1f1946360b2a44d00920e2092e5e4acd139a1964befad4eb0bf3ce96002` |
+| `0.8.0-draft.2` | `0.2.0` | `ab692c1a5a0f7e5f29be1940aa8c64a56d4620be0a19d00cf0a64680b7e517fa` |
+| `0.8.0-draft.1` | `0.1.0` | `4ceb6042c3fd31703199cd3db869ec5c35c17d2fe9ab7b2f5b96a2a3af0cebe4` |
+
+The validator package embeds the schema and executable behavior for each
+selector. npm integrity and trusted-publishing provenance identify released
+package bytes; specification repository tags and commits are informational.
 
 ## Usage
 
@@ -132,9 +137,9 @@ Structural paths start with AJV's instance path. A `required` error appends its
 
 ## Support metadata
 
-The package exports frozen `supportedSpecifications`, `supportedProtocolVersions`, and `specificationProvenance` values. Provenance records include the snapshot tag, recorded schema URI, and embedded schema SHA-256 digest. Public validation dispatches through a registry keyed by exact specification selectors. The current repository selector set is `0.8.0-draft.1`, `0.8.0-draft.2`, `0.8.0-draft.3`, `0.8.0-draft.4`, `0.8.0-rc.1`, and `0.8.0-rc.2`; the protocol-version export is the deduplicated union supported by those snapshots.
+The package exports frozen `supportedSpecifications`, `supportedProtocolVersions`, and `specificationProvenance` values. Provenance records include the snapshot tag, recorded schema URI, and embedded schema SHA-256 digest. Public validation dispatches through a registry keyed by exact specification selectors. The current repository selector set is `0.8.0-draft.1`, `0.8.0-draft.2`, `0.8.0-draft.3`, `0.8.0-draft.4`, `0.8.0-rc.1`, `0.8.0-rc.2`, and `0.8.0-rc.3`; the protocol-version export is the deduplicated union supported by those snapshots.
 
-RC.2 also exports the frozen `mcpExtensionCatalogue` and
+RC.2 and RC.3 also export the frozen `mcpExtensionCatalogue` and
 `mcpExtensionMaturity` classifier. The catalogue pins its authoritative source,
 effective date, and official or experimental identifier assignments. Catalogue
 recognition establishes authority and maturity only; it does not validate
@@ -142,10 +147,10 @@ extension-specific settings.
 
 npm package SemVer tracks implementation releases independently from specification snapshot identity. Adding a later snapshot is additive: it must use a sibling implementation and selector rather than changing an existing snapshot's schema, semantics, metadata, fixtures, or results.
 
-The RC.1 component resolver has one maintainer-approved additive tooling
-correction: successful substitutions also report authored and terminal target
-paths. The correction does not change the RC.1 schema, validation results,
-diagnostics, or fixtures and is recorded in the integrity manifest.
+The RC.1, RC.2, and RC.3 component resolvers report authored and terminal target
+paths for successful substitutions. The additive tooling corrections do not
+change snapshot schemas, validation results, diagnostics, or fixtures and are
+recorded in the integrity manifest.
 
 The runtime bundles its schema, performs no network fetches for external schema references, and imports no Node.js built-ins. Unresolved external Tool-schema references produce incomplete-validation warnings and are preserved. All three ESM entry points support Node.js 20 or later and browser bundlers.
 

package/index.d.ts

@@ -1,4 +1,4 @@
-export type McpDescriptionSpecification = '0.8.0-draft.1' | '0.8.0-draft.2' | '0.8.0-draft.3' | '0.8.0-draft.4' | '0.8.0-rc.1' | '0.8.0-rc.2';
+export type McpDescriptionSpecification = '0.8.0-draft.1' | '0.8.0-draft.2' | '0.8.0-draft.3' | '0.8.0-draft.4' | '0.8.0-rc.1' | '0.8.0-rc.2' | '0.8.0-rc.3';
 
 export type SupportedProtocolVersion =
   | '2024-11-05'
@@ -38,7 +38,7 @@ export interface McpDescriptionComponentResolutionResult {
 }
 
 export interface ResolveMcpDescriptionComponentReferencesOptions {
-  readonly specification: '0.8.0-rc.1';
+  readonly specification: '0.8.0-rc.1' | '0.8.0-rc.2' | '0.8.0-rc.3';
 }
 
 export type McpExtensionMaturity = 'official' | 'experimental' | 'uncatalogued';
@@ -86,6 +86,11 @@ export interface SpecificationProvenance {
     readonly schemaUri: 'https://mcpdesc.org/schema/mcp-description/0.8.0-rc.2.json';
     readonly schemaSha256: '40f6775dde052224114e91d6aa484d826eecf56b77f7ac87b4cf707ffbcb6ce8';
   };
+  readonly '0.8.0-rc.3': {
+    readonly snapshotTag: 'v0.8.0-rc.3';
+    readonly schemaUri: 'https://mcpdesc.org/schema/mcp-description/0.8.0-rc.3.json';
+    readonly schemaSha256: 'a9c3ff77ba37c72362909f538f6e957d055e6fdb372f8b3d529e3651af3fecf4';
+  };
 }
 
 export interface ResolveMcpDescriptionSpecificationOptions {
@@ -109,7 +114,7 @@ export type McpDescriptionSpecificationResolution =
   | ResolvedMcpDescriptionSpecification
   | UnresolvedMcpDescriptionSpecification;
 
-export declare const supportedSpecifications: readonly ['0.8.0-draft.1', '0.8.0-draft.2', '0.8.0-draft.3', '0.8.0-draft.4', '0.8.0-rc.1', '0.8.0-rc.2'];
+export declare const supportedSpecifications: readonly ['0.8.0-draft.1', '0.8.0-draft.2', '0.8.0-draft.3', '0.8.0-draft.4', '0.8.0-rc.1', '0.8.0-rc.2', '0.8.0-rc.3'];
 
 export declare const supportedProtocolVersions: readonly [
   '2024-11-05',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpdesc/validator",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Structural and semantic validation for MCP Description snapshots",
   "type": "module",
   "types": "./index.d.ts",

package/src/index.js

@@ -4,7 +4,10 @@ import * as draft3 from './snapshots/0.8.0-draft.3/index.js';
 import * as draft4 from './snapshots/0.8.0-draft.4/index.js';
 import * as rc1 from './snapshots/0.8.0-rc.1/index.js';
 import * as rc2 from './snapshots/0.8.0-rc.2/index.js';
+import * as rc3 from './snapshots/0.8.0-rc.3/index.js';
 import { resolveComponentReferences as resolveRc1ComponentReferences } from './snapshots/0.8.0-rc.1/semantic.js';
+import { resolveComponentReferences as resolveRc2ComponentReferences } from './snapshots/0.8.0-rc.2/semantic.js';
+import { resolveComponentReferences as resolveRc3ComponentReferences } from './snapshots/0.8.0-rc.3/semantic.js';
 import {
   mcpExtensionCatalogue,
   mcpExtensionMaturity
@@ -18,7 +21,14 @@ const snapshots = Object.freeze({
   [draft3.specification]: draft3,
   [draft4.specification]: draft4,
   [rc1.specification]: rc1,
-  [rc2.specification]: rc2
+  [rc2.specification]: rc2,
+  [rc3.specification]: rc3
+});
+
+const componentResolvers = Object.freeze({
+  '0.8.0-rc.1': resolveRc1ComponentReferences,
+  '0.8.0-rc.2': resolveRc2ComponentReferences,
+  '0.8.0-rc.3': resolveRc3ComponentReferences
 });
 
 const schemaUris = Object.freeze({
@@ -27,7 +37,8 @@ const schemaUris = Object.freeze({
   '0.8.0-draft.3': 'https://mcpdesc.org/schema/0.8.0.json',
   '0.8.0-draft.4': 'https://mcpdesc.org/schema/mcp-description/0.8.0-draft.4.json',
   '0.8.0-rc.1': 'https://mcpdesc.org/schema/mcp-description/0.8.0-rc.1.json',
-  '0.8.0-rc.2': 'https://mcpdesc.org/schema/mcp-description/0.8.0-rc.2.json'
+  '0.8.0-rc.2': 'https://mcpdesc.org/schema/mcp-description/0.8.0-rc.2.json',
+  '0.8.0-rc.3': 'https://mcpdesc.org/schema/mcp-description/0.8.0-rc.3.json'
 });
 
 export const supportedSpecifications = Object.freeze(Object.keys(snapshots));
@@ -158,9 +169,9 @@ export function resolveMcpDescriptionComponentReferences(document, options) {
   if (!options || typeof options !== 'object' || Array.isArray(options) || !Object.hasOwn(options, 'specification')) {
     throw new TypeError('options.specification is required');
   }
-  if (options.specification !== '0.8.0-rc.1') {
+  if (!Object.hasOwn(componentResolvers, options.specification)) {
     throw new RangeError(`Component reference resolution does not support specification: ${String(options.specification)}`);
   }
 
-  return resolveRc1ComponentReferences(document);
+  return componentResolvers[options.specification](document);
 }

package/src/snapshots/0.8.0-rc.2/semantic.js

@@ -62,6 +62,7 @@ function componentDiagnostic(code, rel, message, path) {
 export function resolveComponentReferences(document, rel = 'document') {
   const resolved = structuredClone(document);
   const diagnostics = [];
+  const provenance = [];
   let substitutions = 0;
 
   function resolve(reference, expectedNamespace, path, stack = []) {
@@ -75,7 +76,7 @@ export function resolveComponentReferences(document, rel = 'document') {
         `must target #/components/${expectedNamespace}, not #/components/${namespace}`,
         path
       ));
-      return reference;
+      return { value: reference };
     }
 
     const key = `${namespace}/${name}`;
@@ -86,7 +87,7 @@ export function resolveComponentReferences(document, rel = 'document') {
         `forms a cycle through ${[...stack, key].join(' -> ')}`,
         path
       ));
-      return reference;
+      return { value: reference };
     }
 
     const target = document?.components?.[namespace]?.[name];
@@ -97,18 +98,29 @@ export function resolveComponentReferences(document, rel = 'document') {
         `targets missing component ${JSON.stringify(reference.$componentRef)}`,
         path
       ));
-      return reference;
+      return { value: reference };
     }
     substitutions += 1;
     return isReferenceObject(target)
       ? resolve(target, expectedNamespace, path, [...stack, key])
-      : structuredClone(target);
+      : {
+          value: structuredClone(target),
+          targetPath: ['components', namespace, name]
+        };
+  }
+
+  function substitute(reference, expectedNamespace, path, stack = []) {
+    const result = resolve(reference, expectedNamespace, path, stack);
+    if (result.targetPath) {
+      provenance.push({ referencePath: path, targetPath: result.targetPath });
+    }
+    return result.value;
   }
 
   for (const namespace of componentNamespaces) {
     for (const [name, value] of Object.entries(document?.components?.[namespace] ?? {})) {
       if (isReferenceObject(value)) {
-        resolved.components[namespace][name] = resolve(value, namespace, ['components', namespace, name], [`${namespace}/${name}`]);
+        resolved.components[namespace][name] = substitute(value, namespace, ['components', namespace, name], [`${namespace}/${name}`]);
       }
     }
   }
@@ -124,7 +136,7 @@ export function resolveComponentReferences(document, rel = 'document') {
       if (collection === 'tools') {
         for (const field of ['inputSchema', 'outputSchema']) {
           if (isReferenceObject(declaration[field])) {
-            resolvedDeclaration[field] = resolve(declaration[field], 'schemas', [collection, declarationIndex, field]);
+            resolvedDeclaration[field] = substitute(declaration[field], 'schemas', [collection, declarationIndex, field]);
           }
         }
       }
@@ -138,7 +150,7 @@ export function resolveComponentReferences(document, rel = 'document') {
             : 'promptExamples';
       for (const [name, example] of Object.entries(declaration.examples ?? {})) {
         if (isReferenceObject(example)) {
-          resolvedDeclaration.examples[name] = resolve(
+          resolvedDeclaration.examples[name] = substitute(
             example,
             exampleNamespace,
             [collection, declarationIndex, 'examples', name]
@@ -152,7 +164,7 @@ export function resolveComponentReferences(document, rel = 'document') {
     for (const [declarationIndex, declaration] of (document?.[collection] ?? []).entries()) {
       for (const [elicitationIndex, elicitation] of (declaration.elicitations ?? []).entries()) {
         if (isReferenceObject(elicitation.requestedSchema)) {
-          resolved[collection][declarationIndex].elicitations[elicitationIndex].requestedSchema = resolve(
+          resolved[collection][declarationIndex].elicitations[elicitationIndex].requestedSchema = substitute(
             elicitation.requestedSchema,
             'schemas',
             [collection, declarationIndex, 'elicitations', elicitationIndex, 'requestedSchema']
@@ -162,7 +174,7 @@ export function resolveComponentReferences(document, rel = 'document') {
     }
   }
 
-  return { document: resolved, diagnostics, substitutions };
+  return { document: resolved, diagnostics, substitutions, provenance };
 }
 
 function structuralPath(document, error) {