@mcpdesc/validator 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,14 @@
 
 Isomorphic structural and semantic validation for immutable MCP Description specification snapshots.
 
-The initial implementation supports exactly MCP Description `0.8.0-draft.1`, bound to tag `v0.8.0-draft.1` and the embedded `schemas/mcp-description/0.8.0.json` SHA-256 digest `4ceb6042c3fd31703199cd3db869ec5c35c17d2fe9ab7b2f5b96a2a3af0cebe4`.
+Version `0.2.0` cumulatively supports these immutable snapshots:
+
+| 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` |
+
+This cumulative release is intended to receive the npm `latest` dist-tag after the Draft 2 tag and tarball are reviewed. Repository changes alone do not publish the package or create either tag.
 
 ## Usage
 
@@ -10,7 +17,7 @@ The initial implementation supports exactly MCP Description `0.8.0-draft.1`, bou
 import { validateMcpDescription } from '@mcpdesc/validator';
 
 const result = validateMcpDescription(parsedDocument, {
-  specification: '0.8.0-draft.1'
+  specification: '0.8.0-draft.2'
 });
 
 if (!result.valid) {
@@ -44,10 +51,25 @@ Structural paths start with AJV's instance path. A `required` error appends its
 
 ## Support metadata
 
-The package exports frozen `supportedSpecifications`, `supportedProtocolVersions`, and `specificationProvenance` values. npm package SemVer tracks implementation releases independently from specification snapshot identity. A future draft snapshot must use a sibling implementation and selector rather than changing Draft 1 behavior.
+The package exports frozen `supportedSpecifications`, `supportedProtocolVersions`, and `specificationProvenance` values. Public validation dispatches through a registry keyed by exact specification selectors. The current selector set is `0.8.0-draft.1` and `0.8.0-draft.2`; 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.
 
+## Snapshot lifecycle
+
+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.
+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.
+
+Supporting code does not authorize publication. During release review, a maintainer explicitly decides the validator package version and intended npm dist-tag so the reviewed specification-tag commit contains the chosen package metadata. Only after that specification snapshot is tagged does a maintainer review the tarball and push an annotated `validator-v<semver>` tag. The trusted-publishing workflow requires that exact tag/package version match, reruns the package checks, and publishes SemVer prereleases with npm `next` or stable versions with `latest`. Repository scripts and other CI workflows do not choose versions, create release tags, or publish packages. No package version or publication choice for a later draft is made by this lifecycle description.
+
 ## Development checks
 
 From the repository root:
@@ -59,4 +81,4 @@ npm run test:browser --workspace @mcpdesc/validator
 npm run test:package --workspace @mcpdesc/validator
 ```
 
-The package test covers every official Draft 1 valid, invalid, and warning fixture. The other checks compile the declarations, build for a browser target, and inspect `npm pack --dry-run --json` against the intended tarball contents.
+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 both runtime snapshots for a browser target, and inspect `npm pack --dry-run --json` against the intended tarball contents, including both runtime snapshots and exclusion of test snapshots.

package/index.d.ts

@@ -1,4 +1,4 @@
-export type McpDescriptionSpecification = '0.8.0-draft.1';
+export type McpDescriptionSpecification = '0.8.0-draft.1' | '0.8.0-draft.2';
 
 export type SupportedProtocolVersion =
   | '2024-11-05'
@@ -26,11 +26,17 @@ export interface ValidateMcpDescriptionOptions {
 }
 
 export interface SpecificationProvenance {
-  readonly snapshotTag: 'v0.8.0-draft.1';
-  readonly schemaSha256: '4ceb6042c3fd31703199cd3db869ec5c35c17d2fe9ab7b2f5b96a2a3af0cebe4';
+  readonly '0.8.0-draft.1': {
+    readonly snapshotTag: 'v0.8.0-draft.1';
+    readonly schemaSha256: '4ceb6042c3fd31703199cd3db869ec5c35c17d2fe9ab7b2f5b96a2a3af0cebe4';
+  };
+  readonly '0.8.0-draft.2': {
+    readonly snapshotTag: 'v0.8.0-draft.2';
+    readonly schemaSha256: 'ab692c1a5a0f7e5f29be1940aa8c64a56d4620be0a19d00cf0a64680b7e517fa';
+  };
 }
 
-export declare const supportedSpecifications: readonly ['0.8.0-draft.1'];
+export declare const supportedSpecifications: readonly ['0.8.0-draft.1', '0.8.0-draft.2'];
 
 export declare const supportedProtocolVersions: readonly [
   '2024-11-05',
@@ -40,9 +46,7 @@ export declare const supportedProtocolVersions: readonly [
   '2026-07-28'
 ];
 
-export declare const specificationProvenance: Readonly<{
-  readonly '0.8.0-draft.1': Readonly<SpecificationProvenance>;
-}>;
+export declare const specificationProvenance: Readonly<SpecificationProvenance>;
 
 export declare function validateMcpDescription(
   document: unknown,

package/package.json

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

package/src/index.js

@@ -1,28 +1,30 @@
-import {
-  schemaSha256,
-  snapshotTag,
-  specification,
-  supportedProtocolVersions,
-  validate
-} from './snapshots/0.8.0-draft.1/index.js';
+import * as draft1 from './snapshots/0.8.0-draft.1/index.js';
+import * as draft2 from './snapshots/0.8.0-draft.2/index.js';
 
-export const supportedSpecifications = Object.freeze([specification]);
-export { supportedProtocolVersions };
-
-export const specificationProvenance = Object.freeze({
-  [specification]: Object.freeze({
-    snapshotTag,
-    schemaSha256
-  })
+const snapshots = Object.freeze({
+  [draft1.specification]: draft1,
+  [draft2.specification]: draft2
 });
 
+export const supportedSpecifications = Object.freeze(Object.keys(snapshots));
+export const supportedProtocolVersions = Object.freeze([
+  ...new Set(Object.values(snapshots).flatMap((snapshot) => snapshot.supportedProtocolVersions))
+]);
+
+export const specificationProvenance = Object.freeze(Object.fromEntries(
+  Object.entries(snapshots).map(([selector, snapshot]) => [selector, Object.freeze({
+    snapshotTag: snapshot.snapshotTag,
+    schemaSha256: snapshot.schemaSha256
+  })])
+));
+
 export function validateMcpDescription(document, options) {
   if (!options || typeof options !== 'object' || Array.isArray(options) || !Object.hasOwn(options, 'specification')) {
     throw new TypeError('options.specification is required');
   }
-  if (options.specification !== specification) {
+  if (typeof options.specification !== 'string' || !Object.hasOwn(snapshots, options.specification)) {
     throw new RangeError(`Unsupported MCP Description specification: ${String(options.specification)}`);
   }
 
-  return validate(document);
+  return snapshots[options.specification].validate(document);
 }