@mcpdesc/validator 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to `@mcpdesc/validator` are documented in this file.
+
+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.5.0] - 2026-08-31
+
+### Added
+
+- Added `resolveMcpDescriptionSpecification` for resolving an immutable validator selector from a document's `$schema` identity or checking an exact caller-supplied selector.
+- Added each snapshot's recorded schema URI to `specificationProvenance`.
+- Added the `@mcpdesc/validator/standalone` entry for strict-CSP browsers. It preserves the synchronous public API without `eval`, `new Function`, Node.js built-ins, network schema retrieval, or WASM.
+- Added the immutable `0.8.0-rc.1` selector with the release candidate's canonical schema identity and published schema digest.
+
+## [0.4.0] - 2026-08-29
+
+### Added
+
+- Added the immutable `0.8.0-draft.4` selector, embedded schema, semantic implementation, and frozen fixture corpus.
+- Added Draft 4 schema-digest and snapshot metadata checks while preserving the Draft 1 through Draft 3 implementations.
+
+## [0.3.0] - 2026-08-27
+
+### Added
+
+- Added the immutable `0.8.0-draft.3` selector, embedded schema, semantic implementation, and frozen fixture corpus.
+- Added Draft 3 to the cumulative browser bundle, declarations, support metadata, and package-content checks.
+
+## [0.2.0] - 2026-08-27
+
+### Added
+
+- Added the immutable `0.8.0-draft.2` selector as a sibling implementation without changing Draft 1 behavior.
+- Added cumulative selector dispatch, protocol-version metadata, declarations, browser checks, and a frozen Draft 2 fixture corpus.
+
+## [0.1.0] - 2026-08-25
+
+### Added
+
+- Published the initial reusable validator package for the immutable `0.8.0-draft.1` snapshot.
+- 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/mcpdesc-specification/compare/validator-v0.5.0...HEAD
+[0.5.0]: https://github.com/mcpdesc/mcpdesc-specification/compare/17cc533e79b19ea2dbc1edcf06e30ba68a7d9b79...validator-v0.5.0
+[0.4.0]: https://www.npmjs.com/package/@mcpdesc/validator/v/0.4.0
+[0.3.0]: https://github.com/mcpdesc/mcpdesc-specification/releases/tag/validator-v0.3.0
+[0.2.0]: https://www.npmjs.com/package/@mcpdesc/validator/v/0.2.0
+[0.1.0]: https://github.com/mcpdesc/mcpdesc-specification/releases/tag/validator-v0.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Isomorphic structural and semantic validation for immutable MCP Description specification snapshots.
 
-Version `0.4.0` cumulatively supports these immutable snapshots and is intended for npm `latest` after the Draft 4 specification tag and package tarball are reviewed.
+Version `0.5.0` cumulatively supports these immutable snapshots and is prepared for npm `latest` after the RC.1 specification tag and package tarball are reviewed.
 
 | Selector | Tag | Embedded schema SHA-256 |
 |---|---|---|
@@ -10,6 +10,7 @@ Version `0.4.0` cumulatively supports these immutable snapshots and is intended
 | `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` |
 
 Repository changes alone do not publish the package or create specification or validator tags.
 
@@ -19,7 +20,7 @@ Repository changes alone do not publish the package or create specification or v
 import { validateMcpDescription } from '@mcpdesc/validator';
 
 const result = validateMcpDescription(parsedDocument, {
-  specification: '0.8.0-draft.4'
+  specification: '0.8.0-rc.1'
 });
 
 if (!result.valid) {
@@ -29,7 +30,50 @@ if (!result.valid) {
 
 Callers provide an already parsed JavaScript value. JSON and YAML parsing are outside this package.
 
-The `options` argument and exact `specification` selector are required. The unqualified selector `0.8.0` is intentionally unsupported because draft iterations are immutable compatibility contracts.
+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.
+
+### Strict CSP browsers
+
+Browser applications that prohibit dynamic code generation can use the CSP-safe standalone entry:
+
+```js
+import { validateMcpDescription } from '@mcpdesc/validator/standalone';
+```
+
+It has the same synchronous API, selectors, diagnostics, and offline external-reference behavior as the default entry. Fixed MCP Description schemas and JSON Schema meta-schemas are precompiled during package development; document-provided Tool and Elicitation schemas use the package's interpreted JSON Schema dependency, so the shipped file contains no `eval` or `new Function`. This compatibility entry is larger and slower than the default AJV-based entry and is JavaScript, not WASM.
+
+## Snapshot resolution
+
+`resolveMcpDescriptionSpecification` resolves an exact validator selector from
+the document's `$schema` identity or checks a caller-supplied exact selector:
+
+```js
+import { resolveMcpDescriptionSpecification } from '@mcpdesc/validator';
+
+const resolution = resolveMcpDescriptionSpecification(parsedDocument);
+if (resolution.status === 'resolved') {
+  console.log(resolution.specification, resolution.provenance);
+} else {
+  console.error(resolution.diagnostics);
+}
+```
+
+Resolution is pure and performs no network retrieval. It does not validate the
+document and never infers a draft snapshot from `mcpdesc: "0.8.0"` alone.
+Draft 4's format-qualified schema URI resolves uniquely. Drafts 1 through 3
+share the legacy `https://mcpdesc.org/schema/0.8.0.json` URI, so that URI is
+ambiguous unless the caller supplies a consistent exact selector:
+
+```js
+const resolution = resolveMcpDescriptionSpecification(parsedDocument, {
+  specification: '0.8.0-draft.3'
+});
+```
+
+Unresolved results distinguish missing, invalid, unknown, ambiguous, and
+contradictory identity, as well as unsupported caller selectors. A supplied
+selector can resolve a document with no `$schema`; when `$schema` is present it
+must match the selected snapshot's recorded schema URI.
 
 ## Result
 
@@ -53,11 +97,11 @@ Structural paths start with AJV's instance path. A `required` error appends its
 
 ## Support metadata
 
-The package exports frozen `supportedSpecifications`, `supportedProtocolVersions`, and `specificationProvenance` values. 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`, and `0.8.0-draft.4`; 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`, and `0.8.0-rc.1`; the protocol-version export is the deduplicated union supported by those snapshots.
 
 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 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. The same ESM entry point supports Node.js 20 or later and browser bundlers.
+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. Both ESM entry points support Node.js 20 or later and browser bundlers.
 
 ## Snapshot lifecycle
 
@@ -65,7 +109,7 @@ For each approved specification snapshot, maintainers:
 
 1. Add a versioned implementation under `src/snapshots/<selector>/` with its exact selector, snapshot tag, embedded schema, schema SHA-256 digest, and semantic rules. Existing snapshot directories remain unchanged.
 2. Freeze the matching fixture corpus under `test/snapshots/<selector>/fixtures/`. Package tests must not read mutable `spec/draft/fixtures/` for an already published selector.
-3. Add the exact selector to the runtime registry and update support metadata, TypeScript declarations, tests, and expected package contents. Unqualified versions, aliases, ranges, and not-yet-published selectors remain unsupported.
+3. Add the exact selector to the runtime registry and update support metadata, TypeScript declarations, tests, the package changelog, and expected package contents. Unqualified versions, aliases, ranges, and not-yet-published selectors remain unsupported.
 4. Run the package and repository validation suites. The schema digest, immutable metadata, fixture behavior, browser bundle, declarations, and tarball contents must all pass.
 
 The test snapshots are repository-only development assets and are excluded from the npm tarball. Runtime snapshot implementations and embedded schemas do ship so installed packages remain self-contained.

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';
+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';
 
 export type SupportedProtocolVersion =
   | '2024-11-05'
@@ -28,23 +28,53 @@ export interface ValidateMcpDescriptionOptions {
 export interface SpecificationProvenance {
   readonly '0.8.0-draft.1': {
     readonly snapshotTag: 'v0.8.0-draft.1';
+    readonly schemaUri: 'https://mcpdesc.org/schema/0.8.0.json';
     readonly schemaSha256: '4ceb6042c3fd31703199cd3db869ec5c35c17d2fe9ab7b2f5b96a2a3af0cebe4';
   };
   readonly '0.8.0-draft.2': {
     readonly snapshotTag: 'v0.8.0-draft.2';
+    readonly schemaUri: 'https://mcpdesc.org/schema/0.8.0.json';
     readonly schemaSha256: 'ab692c1a5a0f7e5f29be1940aa8c64a56d4620be0a19d00cf0a64680b7e517fa';
   };
   readonly '0.8.0-draft.3': {
     readonly snapshotTag: 'v0.8.0-draft.3';
+    readonly schemaUri: 'https://mcpdesc.org/schema/0.8.0.json';
     readonly schemaSha256: '8823c1f1946360b2a44d00920e2092e5e4acd139a1964befad4eb0bf3ce96002';
   };
   readonly '0.8.0-draft.4': {
     readonly snapshotTag: 'v0.8.0-draft.4';
+    readonly schemaUri: 'https://mcpdesc.org/schema/mcp-description/0.8.0-draft.4.json';
     readonly schemaSha256: '93ed03f74059b5b3ce7509a96b59161bdab2c3cf7734397a9bec5a7588d0b03b';
   };
+  readonly '0.8.0-rc.1': {
+    readonly snapshotTag: 'v0.8.0-rc.1';
+    readonly schemaUri: 'https://mcpdesc.org/schema/mcp-description/0.8.0-rc.1.json';
+    readonly schemaSha256: '936a0f24ade501fcabf3d6498c0440c445daa672a575573a35954cee49430ac4';
+  };
+}
+
+export interface ResolveMcpDescriptionSpecificationOptions {
+  readonly specification?: McpDescriptionSpecification;
+}
+
+export interface ResolvedMcpDescriptionSpecification {
+  readonly status: 'resolved';
+  readonly specification: McpDescriptionSpecification;
+  readonly schemaUri: string;
+  readonly provenance: SpecificationProvenance[McpDescriptionSpecification];
+  readonly diagnostics: McpDescriptionDiagnostic[];
 }
 
-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'];
+export interface UnresolvedMcpDescriptionSpecification {
+  readonly status: 'unresolved';
+  readonly diagnostics: McpDescriptionDiagnostic[];
+}
+
+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'];
 
 export declare const supportedProtocolVersions: readonly [
   '2024-11-05',
@@ -56,6 +86,11 @@ export declare const supportedProtocolVersions: readonly [
 
 export declare const specificationProvenance: Readonly<SpecificationProvenance>;
 
+export declare function resolveMcpDescriptionSpecification(
+  document: unknown,
+  options?: ResolveMcpDescriptionSpecificationOptions
+): McpDescriptionSpecificationResolution;
+
 export declare function validateMcpDescription(
   document: unknown,
   options: ValidateMcpDescriptionOptions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpdesc/validator",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Structural and semantic validation for MCP Description snapshots",
   "type": "module",
   "types": "./index.d.ts",
@@ -17,12 +17,18 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./src/index.js"
+    },
+    "./standalone": {
+      "types": "./index.d.ts",
+      "import": "./standalone.js"
     }
   },
   "files": [
     "src/index.js",
     "src/snapshots",
+    "standalone.js",
     "index.d.ts",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE",
     "NOTICE",
@@ -30,12 +36,14 @@
     "MODIFICATIONS.md"
   ],
   "scripts": {
-    "test": "node --test test/*.test.js && npm run test:types && npm run test:browser && npm run test:package",
+    "build:standalone": "node scripts/build-standalone.mjs",
+    "test": "npm run build:standalone && node --test test/*.test.js && npm run test:types && npm run test:browser && npm run test:package",
     "test:browser": "node scripts/check-browser-bundle.mjs",
     "test:package": "node scripts/check-package.mjs",
     "test:types": "tsc --project test/types/tsconfig.json && node scripts/check-declarations.mjs"
   },
   "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "uri-template-matcher": "^1.1.2"
@@ -45,4 +53,4 @@
     "typescript": "^5.9.0",
     "yaml": "^2.9.0"
   }
-}
+}

package/src/index.js

@@ -2,12 +2,22 @@ import * as draft1 from './snapshots/0.8.0-draft.1/index.js';
 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';
 
 const snapshots = Object.freeze({
   [draft1.specification]: draft1,
   [draft2.specification]: draft2,
   [draft3.specification]: draft3,
-  [draft4.specification]: draft4
+  [draft4.specification]: draft4,
+  [rc1.specification]: rc1
+});
+
+const schemaUris = Object.freeze({
+  '0.8.0-draft.1': 'https://mcpdesc.org/schema/0.8.0.json',
+  '0.8.0-draft.2': 'https://mcpdesc.org/schema/0.8.0.json',
+  '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'
 });
 
 export const supportedSpecifications = Object.freeze(Object.keys(snapshots));
@@ -18,10 +28,111 @@ export const supportedProtocolVersions = Object.freeze([
 export const specificationProvenance = Object.freeze(Object.fromEntries(
   Object.entries(snapshots).map(([selector, snapshot]) => [selector, Object.freeze({
     snapshotTag: snapshot.snapshotTag,
+    schemaUri: schemaUris[selector],
     schemaSha256: snapshot.schemaSha256
   })])
 ));
 
+const specificationsBySchemaUri = new Map();
+for (const snapshot of Object.values(snapshots)) {
+  const schemaUri = schemaUris[snapshot.specification];
+  const selectors = specificationsBySchemaUri.get(schemaUri) ?? [];
+  selectors.push(snapshot.specification);
+  specificationsBySchemaUri.set(schemaUri, selectors);
+}
+
+function resolutionDiagnostic(code, message, path = []) {
+  return { code, severity: 'error', message, path };
+}
+
+function resolvedSpecification(specification, diagnostics = []) {
+  const snapshot = snapshots[specification];
+  return {
+    status: 'resolved',
+    specification,
+    schemaUri: schemaUris[specification],
+    provenance: specificationProvenance[specification],
+    diagnostics
+  };
+}
+
+export function resolveMcpDescriptionSpecification(document, options = {}) {
+  const override = options?.specification;
+  if (override !== undefined && (typeof override !== 'string' || !Object.hasOwn(snapshots, override))) {
+    return {
+      status: 'unresolved',
+      diagnostics: [resolutionDiagnostic(
+        'unsupported-specification',
+        `Unsupported MCP Description specification: ${String(override)}`
+      )]
+    };
+  }
+
+  const declaredSchema = document !== null
+    && typeof document === 'object'
+    && !Array.isArray(document)
+    && Object.hasOwn(document, '$schema')
+    ? document.$schema
+    : undefined;
+
+  if (declaredSchema === undefined) {
+    if (override !== undefined) return resolvedSpecification(override);
+    return {
+      status: 'unresolved',
+      diagnostics: [resolutionDiagnostic(
+        'missing-snapshot-identity',
+        'An exact specification selector or recognized $schema identity is required',
+        ['$schema']
+      )]
+    };
+  }
+
+  if (typeof declaredSchema !== 'string') {
+    return {
+      status: 'unresolved',
+      diagnostics: [resolutionDiagnostic(
+        'invalid-schema-identity',
+        '$schema must be a string to resolve an MCP Description specification',
+        ['$schema']
+      )]
+    };
+  }
+
+  const candidates = specificationsBySchemaUri.get(declaredSchema) ?? [];
+  if (override !== undefined) {
+    if (schemaUris[override] === declaredSchema) return resolvedSpecification(override);
+    return {
+      status: 'unresolved',
+      diagnostics: [resolutionDiagnostic(
+        'contradictory-snapshot-identity',
+        `$schema ${JSON.stringify(declaredSchema)} does not identify specification ${JSON.stringify(override)}`,
+        ['$schema']
+      )]
+    };
+  }
+
+  if (candidates.length === 1) return resolvedSpecification(candidates[0]);
+  if (candidates.length > 1) {
+    return {
+      status: 'unresolved',
+      diagnostics: [resolutionDiagnostic(
+        'ambiguous-schema-identity',
+        `$schema ${JSON.stringify(declaredSchema)} is shared by ${candidates.join(', ')} and does not select one immutable snapshot`,
+        ['$schema']
+      )]
+    };
+  }
+
+  return {
+    status: 'unresolved',
+    diagnostics: [resolutionDiagnostic(
+      'unknown-schema-identity',
+      `Unknown MCP Description $schema identity: ${JSON.stringify(declaredSchema)}`,
+      ['$schema']
+    )]
+  };
+}
+
 export function validateMcpDescription(document, options) {
   if (!options || typeof options !== 'object' || Array.isArray(options) || !Object.hasOwn(options, 'specification')) {
     throw new TypeError('options.specification is required');