@mcpdesc/validator 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ 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.8.0] - 2026-09-03
+
+### Added
+
+- Added RC.1-only `resolveMcpDescriptionComponentReferences` to the default,
+	browser, and standalone entries, returning the existing resolved clone,
+	diagnostics, and substitution count plus deterministic terminal-target
+	provenance.
+
+### Changed
+
+- Recorded the maintainer-approved additive provenance correction to the RC.1
+	snapshot implementation. Its schema, conformance results, diagnostics, and
+	frozen fixtures remain unchanged.
+
+## [0.7.1] - 2026-09-02
+
+### Changed
+
+- Added an explicit package-specific homepage and expanded the README with the
+	validator's purpose, boundaries, result model, installation, and newest-first
+	snapshot support.
+
 ## [0.7.0] - 2026-09-02
 
 ### Changed
@@ -69,7 +94,9 @@ Dates for published releases are the UTC publication dates recorded by npm.
 - Added synchronous structural and semantic validation for parsed JavaScript values with deterministic diagnostics and exact selector dispatch.
 - Added ESM browser support, TypeScript declarations, embedded schema provenance, frozen fixtures, and package-content checks.
 
-[Unreleased]: https://github.com/mcpdesc/core/compare/validator-v0.7.0...HEAD
+[Unreleased]: https://github.com/mcpdesc/core/compare/validator-v0.8.0...HEAD
+[0.8.0]: https://github.com/mcpdesc/core/compare/validator-v0.7.1...validator-v0.8.0
+[0.7.1]: https://github.com/mcpdesc/core/compare/validator-v0.7.0...validator-v0.7.1
 [0.7.0]: https://github.com/mcpdesc/core/releases/tag/validator-v0.7.0
 [0.6.0]: https://github.com/mcpdesc/mcpdesc-specification/compare/validator-v0.5.0...validator-v0.6.0
 [0.5.0]: https://github.com/mcpdesc/mcpdesc-specification/compare/17cc533e79b19ea2dbc1edcf06e30ba68a7d9b79...validator-v0.5.0

package/README.md

@@ -1,36 +1,60 @@
 # @mcpdesc/validator
 
-Isomorphic structural and semantic validation for immutable MCP Description specification snapshots.
+Validate parsed MCP Description documents against exact, immutable specification
+snapshots. The package:
 
-Version `0.7.0` cumulatively supports these immutable snapshots. This release
-moves package maintenance from the MCP Description specification repository to
-the MCP Description tooling repository without changing conformance behavior.
+- checks document structure against the snapshot's embedded JSON Schema;
+- applies semantic rules that JSON Schema alone cannot express;
+- returns deterministic error and warning diagnostics with document paths; and
+- runs synchronously and offline in Node.js 20+ and browser bundles.
 
-| Selector | Tag | Embedded schema SHA-256 |
-|---|---|---|
-| `0.8.0-draft.1` | `v0.8.0-draft.1` | `4ceb6042c3fd31703199cd3db869ec5c35c17d2fe9ab7b2f5b96a2a3af0cebe4` |
-| `0.8.0-draft.2` | `v0.8.0-draft.2` | `ab692c1a5a0f7e5f29be1940aa8c64a56d4620be0a19d00cf0a64680b7e517fa` |
-| `0.8.0-draft.3` | `v0.8.0-draft.3` | `8823c1f1946360b2a44d00920e2092e5e4acd139a1964befad4eb0bf3ce96002` |
-| `0.8.0-draft.4` | `v0.8.0-draft.4` | `93ed03f74059b5b3ce7509a96b59161bdab2c3cf7734397a9bec5a7588d0b03b` |
-| `0.8.0-rc.1` | `v0.8.0-rc.1` | `936a0f24ade501fcabf3d6498c0440c445daa672a575573a35954cee49430ac4` |
+Use it when accepting, generating, migrating, or transforming MCP Description
+documents and you need to know whether the result conforms to a specific
+published draft or release candidate. It validates MCP Description documents,
+not live MCP servers or MCP protocol messages.
 
-Repository changes alone do not publish the package or create specification or validator tags.
+## Install
 
-## Usage
+```bash
+npm install @mcpdesc/validator
+```
+
+## Quick start
 
 ```js
 import { validateMcpDescription } from '@mcpdesc/validator';
 
 const result = validateMcpDescription(parsedDocument, {
-  specification: '0.8.0-rc.1'
+  specification: '0.8.0-rc.1',
 });
 
+for (const diagnostic of result.diagnostics) {
+  console.log(diagnostic.severity, diagnostic.path, diagnostic.message);
+}
+
 if (!result.valid) {
-  console.error(result.diagnostics);
+  // At least one error diagnostic was returned.
 }
 ```
 
-Callers provide an already parsed JavaScript value. JSON and YAML parsing are outside this package.
+Callers provide an already parsed JavaScript value. JSON and YAML parsing, file
+access, network access, and live-server inspection are outside this package.
+The exact `specification` selector is required so validation never changes when
+a later draft is published.
+
+## Supported snapshots
+
+Version `0.8.0` supports these immutable snapshots, newest first:
+
+| Selector | Tag | Embedded schema SHA-256 |
+|---|---|---|
+| `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` |
+
+## Usage
 
 The `options` argument and exact `specification` selector are required. The unqualified selector `0.8.0` is intentionally unsupported because draft and release-candidate iterations are immutable compatibility contracts.
 
@@ -111,6 +135,11 @@ The package exports frozen `supportedSpecifications`, `supportedProtocolVersions
 
 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 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.
 
 ## Snapshot lifecycle

package/index.d.ts

@@ -25,6 +25,22 @@ export interface ValidateMcpDescriptionOptions {
   specification: McpDescriptionSpecification;
 }
 
+export interface McpDescriptionComponentReferenceProvenance {
+  readonly referencePath: Array<string | number>;
+  readonly targetPath: Array<string | number>;
+}
+
+export interface McpDescriptionComponentResolutionResult {
+  readonly document: unknown;
+  readonly diagnostics: McpDescriptionDiagnostic[];
+  readonly substitutions: number;
+  readonly provenance: McpDescriptionComponentReferenceProvenance[];
+}
+
+export interface ResolveMcpDescriptionComponentReferencesOptions {
+  readonly specification: '0.8.0-rc.1';
+}
+
 export interface SpecificationProvenance {
   readonly '0.8.0-draft.1': {
     readonly snapshotTag: 'v0.8.0-draft.1';
@@ -94,4 +110,9 @@ export declare function resolveMcpDescriptionSpecification(
 export declare function validateMcpDescription(
   document: unknown,
   options: ValidateMcpDescriptionOptions
-): McpDescriptionValidationResult;
+): McpDescriptionValidationResult;
+
+export declare function resolveMcpDescriptionComponentReferences(
+  document: unknown,
+  options: ResolveMcpDescriptionComponentReferencesOptions
+): McpDescriptionComponentResolutionResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpdesc/validator",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Structural and semantic validation for MCP Description snapshots",
   "type": "module",
   "types": "./index.d.ts",
@@ -10,6 +10,8 @@
     "url": "git+https://github.com/mcpdesc/core.git",
     "directory": "packages/validator"
   },
+  "homepage": "https://github.com/mcpdesc/core/tree/main/packages/validator#readme",
+  "bugs": "https://github.com/mcpdesc/core/issues",
   "engines": {
     "node": ">=20"
   },

package/src/index.js

@@ -3,6 +3,7 @@ import * as draft2 from './snapshots/0.8.0-draft.2/index.js';
 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 { resolveComponentReferences as resolveRc1ComponentReferences } from './snapshots/0.8.0-rc.1/semantic.js';
 
 const snapshots = Object.freeze({
   [draft1.specification]: draft1,
@@ -142,4 +143,15 @@ export function validateMcpDescription(document, options) {
   }
 
   return snapshots[options.specification].validate(document);
+}
+
+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') {
+    throw new RangeError(`Component reference resolution does not support specification: ${String(options.specification)}`);
+  }
+
+  return resolveRc1ComponentReferences(document);
 }

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

@@ -61,11 +61,12 @@ 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 = []) {
     const match = /^#\/components\/([^/]+)\/([^/]+)$/.exec(reference?.$componentRef ?? '');
-    if (!match) return reference;
+    if (!match) return { value: reference };
     const [, namespace, name] = match;
     if (namespace !== expectedNamespace) {
       diagnostics.push(componentDiagnostic(
@@ -74,7 +75,7 @@ export function resolveComponentReferences(document, rel = 'document') {
         `must target #/components/${expectedNamespace}, not #/components/${namespace}`,
         path
       ));
-      return reference;
+      return { value: reference };
     }
 
     const key = `${namespace}/${name}`;
@@ -85,7 +86,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];
@@ -96,18 +97,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}`]);
       }
     }
   }
@@ -123,7 +135,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]);
           }
         }
       }
@@ -137,7 +149,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]
@@ -151,7 +163,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']
@@ -161,7 +173,7 @@ export function resolveComponentReferences(document, rel = 'document') {
     }
   }
 
-  return { document: resolved, diagnostics, substitutions };
+  return { document: resolved, diagnostics, substitutions, provenance };
 }
 
 function structuralPath(document, error) {