npm install @reaatech/mcp-schema-evolution
# or
pnpm add @reaatech/mcp-schema-evolution

import { diffToolSnapshots, loadToolsFromFile, type SchemaChange } from "@reaatech/mcp-schema-evolution";
 
// Load snapshots from disk
const v1 = loadToolsFromFile("snapshots/v1.json");
const v2 = loadToolsFromFile("snapshots/v2.json");
 
if (v1.ok && v2.ok) {
  const result = diffToolSnapshots(v1.value, v2.value);
 
  if (result.ok) {
    const changes: SchemaChange[] = result.value;
    const breaking = changes.filter((c) => c.type === "breaking");
    const nonBreaking = changes.filter((c) => c.type === "non-breaking");
 
    console.log(`${changes.length} changes: ${breaking.length} breaking, ${nonBreaking.length} non-breaking`);
 
    for (const change of changes) {
      console.log(`[${change.severity}] ${change.toolName} ${change.path}: ${change.description}`);
      if (change.migration) {
        console.log(`  → ${change.migration.suggestion}`);
      }
    }
  } else {
    console.error(result.error.message);
  }
}

import { diffToolSnapshots } from "@reaatech/mcp-schema-evolution";
 
const result = diffToolSnapshots(oldTools, newTools, { renameThreshold: 0.7 });

interface Tool {
  name: string;
  description?: string;
  inputSchema: {
    $schema?: string;
    type: "object";
    properties?: Record<string, unknown>;
    required?: string[];
  };
}

interface SchemaChange {
  type: ChangeType;              // "breaking" | "non-breaking" | "patch"
  category: ChangeCategory;      // see classification table below
  toolName: string;              // affected MCP tool name
  path: string;                  // dot-separated path (e.g. "search.inputSchema.properties.query")
  description: string;           // human-readable change description
  severity: ChangeSeverity;      // "high" | "medium" | "low"
  migration?: MigrationGuidance; // actionable migration advice
}

interface MigrationGuidance {
  suggestion: string;     // human-readable migration advice
  codeExample?: string;   // optional code example
  automated: boolean;     // true if tooling can handle this automatically
}

interface DetectedChange {
  category: ChangeCategory;
  toolName: string;
  path: string;
  description: string;
  oldValue?: unknown;
  newValue?: unknown;
  required?: boolean;       // only for field_added
  constraintName?: string;   // only for constraint_changed
}

interface FieldRename {
  from: string;         // old field name
  to: string;           // new field name
  confidence: number;   // similarity score (0–1)
}

type Result<T> = { ok: true; value: T } | { ok: false; error: EvolutionError };

class EvolutionError extends Error {
  readonly code: string;
  readonly path: string | undefined;
  readonly suggestion: string | undefined;
}

type ChangeType = "breaking" | "non-breaking" | "patch";
type ChangeSeverity = "high" | "medium" | "low";
type ChangeCategory =
  | "tool_added"
  | "tool_removed"
  | "field_added"
  | "field_removed"
  | "field_renamed"
  | "type_changed"
  | "required_changed"
  | "default_changed"
  | "constraint_changed"
  | "deprecated";
type ToolSnapshot = Tool[];
type SemVer = `${number}.${number}.${number}`;

import {
  diffToolSnapshots,
  loadToolsFromFile,
  classifyChange,
  type DetectedChange,
  type SchemaChange,
} from "@reaatech/mcp-schema-evolution";
 
// Compare snapshots
const result = diffToolSnapshots(oldTools, newTools, { renameThreshold: 0.7 });
if (result.ok) {
  for (const change of result.value) {
    if (change.type === "breaking") {
      console.warn(`BREAKING: ${change.description}`);
      if (change.migration) {
        console.warn(`  Fix: ${change.migration.suggestion}`);
      }
    }
  }
}
 
// Manual classification
const raw: DetectedChange = {
  category: "field_removed",
  toolName: "search",
  path: "search.inputSchema.properties.query",
  description: 'Field "query" removed',
};
const classified: SchemaChange = classifyChange(raw);
// classified.type === "breaking", classified.severity === "high"
 
// Standalone rename detection
import { detectFieldRenames } from "@reaatech/mcp-schema-evolution";
const renames = detectFieldRenames(oldTool, newTool, { threshold: 0.5 });
for (const rename of renames) {
  console.log(`${rename.from} → ${rename.to} (${(rename.confidence * 100).toFixed(0)}%)`);
}