@mcpdesc/validator 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# 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.6.0] - 2026-09-02
+
+### Added
+
+- Added `@mcpdesc/validator/browser` as a descriptive strict-CSP alias for the existing `@mcpdesc/validator/standalone` implementation, with the same API and declarations.
+- Added blocked-code-generation validation coverage, including document-provided schemas, plus esbuild, Vite, runtime-AJV exclusion, and packed-export checks.
+
+### Changed
+
+- Documented the strict-CSP and runtime-compilation behavior of the default, browser, and standalone entries. The default and standalone exports remain unchanged, and no conditional browser export was added.
+
+### Bundle size
+
+- Before this change, the generated standalone artifact was 1,730,897 bytes (195,998 bytes gzip). After adding the zero-source-file browser alias it remains 1,730,897 bytes (195,998 bytes gzip). Minified esbuild bundles of `/browser` and `/standalone` are both 1,752,417 bytes (0-byte delta); the minified Vite `/browser` bundle is 2,088,016 bytes in the same development environment.
+- A metadata-only entry was evaluated but not added. The current public metadata is coupled to the cumulative snapshot registry, and splitting it would introduce another declaration and synchronization boundary without an approved consumer or measured package-level benefit.
+
+## [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.6.0...HEAD
+[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
+[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.6.0` cumulatively supports these immutable snapshots.
 
 | 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,58 @@ 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.
+
+### Entry points
+
+| Entry | Strict CSP without `unsafe-eval` | Fixed MCP Description schemas | Document-provided schemas |
+|---|---|---|---|
+| `@mcpdesc/validator` | No | Compiled by AJV at runtime | Compiled or interpreted at runtime |
+| `@mcpdesc/validator/browser` | Yes | Precompiled during package development | Interpreted at runtime |
+| `@mcpdesc/validator/standalone` | Yes | Precompiled during package development | Interpreted at runtime |
+
+Browser applications that prohibit dynamic code generation should use the descriptive CSP-safe browser entry:
+
+```js
+import { validateMcpDescription } from '@mcpdesc/validator/browser';
+```
+
+The `/browser` entry is a public alias for the existing `/standalone` implementation. `/standalone` remains supported for backward compatibility. Both have 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 neither entry uses `eval` or `new Function` or requires `unsafe-eval`. These entries are larger and slower than the default AJV-based entry and are JavaScript, not WASM.
+
+The default entry remains unchanged and uses AJV runtime compilation. Applications that need dynamic schema compilation can use it where their runtime policy permits dynamic code generation. Importing it may fail when a browser enforces strict CSP. The package intentionally does not select a different implementation through conditional exports; consumers choose the required behavior explicitly.
+
+## 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 +105,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. All three ESM entry points support Node.js 20 or later and browser bundlers.
 
 ## Snapshot lifecycle
 
@@ -65,7 +117,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.
@@ -83,4 +135,4 @@ npm run test:browser --workspace @mcpdesc/validator
 npm run test:package --workspace @mcpdesc/validator
 ```
 
-The package test runs each immutable snapshot against its own frozen valid, invalid, and warning fixture corpus. YAML source fixtures are decoded by the test harness before validation; the public API continues to accept parsed JavaScript values only. The other checks compile the declarations, build all runtime snapshots for a browser target, and inspect `npm pack --dry-run --json` against the intended tarball contents, including all runtime snapshots and exclusion of test snapshots.
+The package test runs each immutable snapshot against its own frozen valid, invalid, and warning fixture corpus. YAML source fixtures are decoded by the test harness before validation; the public API continues to accept parsed JavaScript values only. The other checks compile the declarations, bundle the public browser entry with esbuild and Vite, reject runtime AJV compiler inputs and dynamic code generation in those bundles, and inspect `npm pack --dry-run --json` against the intended tarball contents and declared export targets.

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.6.0",
   "description": "Structural and semantic validation for MCP Description snapshots",
   "type": "module",
   "types": "./index.d.ts",
@@ -17,12 +17,22 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./src/index.js"
+    },
+    "./browser": {
+      "types": "./index.d.ts",
+      "import": "./standalone.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 +40,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"
@@ -43,6 +55,7 @@
   "devDependencies": {
     "esbuild": "^0.25.0",
     "typescript": "^5.9.0",
+    "vite": "^6.4.3",
     "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');