@mortice/mapwright 0.8.0

package/dist/mcp/tools.js

@@ -0,0 +1,902 @@
+import { z } from "zod";
+import path from "node:path";
+import { indexWorkspace, shouldFailFromDiagnostics } from "../catalogue/indexer.js";
+import { loadConfig } from "../catalogue/config.js";
+import { loadCommittedCatalogue } from "../catalogue/store.js";
+import { searchSymbols, getSymbolContext } from "../queries/symbols.js";
+import { getCapabilityContext } from "../queries/capabilities.js";
+import { getPublicApiContext, searchPublicApis } from "../queries/publicApis.js";
+import { getWorkspaceOverview } from "../queries/overview.js";
+import { getBoundedSourcePreview } from "../security/sourceAccess.js";
+import { getDependencyNeighborhood } from "../queries/dependencies.js";
+import { findReuseCandidates } from "../queries/reuseCandidates.js";
+import { listCapabilitiesPage, listDiagnosticsPage, listExamplesPage, listFilesPage, listPackagesPage, listPublicApisPage, listRelationshipsPage, listSymbolsPage } from "../queries/lists.js";
+import { getAdoptionAudit, getAdoptionPlan } from "../queries/adoption.js";
+import { recommendConfig } from "../queries/recommendConfig.js";
+import { getDocumentationTemplate, listDocumentationTemplateIds, listDocumentationTemplates } from "../catalogue/templates.js";
+import { getDogfoodReport } from "../queries/dogfood.js";
+import { loadCataloguePair } from "../comparison/validate.js";
+import { compareCatalogues } from "../comparison/compare.js";
+import { loadComparisonArtefact, writeComparisonArtefact, assertComparisonPathContained } from "../comparison/store.js";
+import { getChangeImpact } from "../comparison/impact.js";
+import { DEFAULT_COMPARISON_OPTIONS } from "../comparison/schema.js";
+import { getChange, getChangeSummary, getCompatibilityReport, listChanges } from "../queries/changes.js";
+import { checkCatalogueDrift } from "../comparison/drift.js";
+export const CATALOGUE_NOT_LOADED_CODE = "catalogue_not_loaded";
+export const CATALOGUE_NOT_LOADED_MESSAGE = "Run load_committed_catalogue or index_workspace first.";
+export const COMPARISON_NOT_LOADED_CODE = "comparison_not_loaded";
+export const COMPARISON_NOT_LOADED_MESSAGE = "Run compare_catalogues or load_comparison first.";
+export function success(data, warnings = []) {
+    return { ok: true, data, warnings, provenance: { source: "mapwright-mcp" } };
+}
+export function failure(code, message) {
+    return { ok: false, error: { code, message }, warnings: [], provenance: { source: "mapwright-mcp" } };
+}
+export function catalogueNotLoadedFailure() {
+    return failure(CATALOGUE_NOT_LOADED_CODE, CATALOGUE_NOT_LOADED_MESSAGE);
+}
+export function comparisonNotLoadedFailure() {
+    return failure(COMPARISON_NOT_LOADED_CODE, COMPARISON_NOT_LOADED_MESSAGE);
+}
+export function catalogueNotLoadedContent() {
+    return { content: [{ type: "text", text: JSON.stringify(catalogueNotLoadedFailure()) }] };
+}
+export function registerTools(server, options = {}) {
+    let latest = options.initialSnapshot;
+    let latestWorkspace = options.initialWorkspace ?? process.cwd();
+    let latestLimits = { maxFileSizeBytes: 512000, maxSourcePreviewLines: 120 };
+    let activeComparison;
+    const setActiveComparison = (next) => {
+        activeComparison = next;
+        options.onComparisonChange?.(next);
+    };
+    server.registerTool("load_committed_catalogue", {
+        description: "Load a committed .mapwright catalogue snapshot without indexing source.",
+        inputSchema: {
+            workspaceRoot: z.string(),
+            catalogueDir: z.string().default(".mapwright")
+        }
+    }, async (args) => {
+        const workspaceRoot = args.workspaceRoot;
+        const { config } = loadConfig({ workspaceRoot });
+        const catalogueDir = args.catalogueDir ?? config.catalogueDir;
+        const loaded = loadCommittedCatalogue(workspaceRoot, catalogueDir);
+        if (!loaded.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(failure(loaded.error.code, loaded.error.message))
+                    }
+                ]
+            };
+        }
+        latestWorkspace = workspaceRoot;
+        latestLimits = {
+            maxFileSizeBytes: config.limits.maxFileSizeBytes,
+            maxSourcePreviewLines: config.limits.maxSourcePreviewLines
+        };
+        latest = loaded.snapshot;
+        options.onSnapshotChange?.(loaded.snapshot, workspaceRoot);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success({
+                        catalogueId: loaded.snapshot.catalogueId,
+                        stats: loaded.snapshot.stats,
+                        source: "committed-catalogue",
+                        schemaVersion: loaded.snapshot.schemaVersion,
+                        identityScheme: loaded.snapshot.identityScheme,
+                        generatorVersion: loaded.snapshot.generator.version
+                    }, loaded.warnings))
+                }
+            ]
+        };
+    });
+    server.registerTool("index_workspace", {
+        description: "Index workspace and write catalogue output.",
+        inputSchema: {
+            workspaceRoot: z.string(),
+            mode: z.enum(["committed", "local", "memory"]).default("committed"),
+            writeCache: z.boolean().default(true)
+        }
+    }, async (args) => {
+        const workspaceRoot = args.workspaceRoot;
+        latestWorkspace = workspaceRoot;
+        const { config } = loadConfig({ workspaceRoot });
+        latestLimits = {
+            maxFileSizeBytes: config.limits.maxFileSizeBytes,
+            maxSourcePreviewLines: config.limits.maxSourcePreviewLines
+        };
+        const { snapshot } = indexWorkspace({
+            workspaceRoot,
+            mode: args.mode,
+            write: args.writeCache
+        });
+        latest = snapshot;
+        options.onSnapshotChange?.(snapshot, workspaceRoot);
+        return { content: [{ type: "text", text: JSON.stringify(success({ catalogueId: snapshot.catalogueId, stats: snapshot.stats })) }] };
+    });
+    server.registerTool("get_workspace_overview", { description: "Get workspace overview.", inputSchema: {} }, async () => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return { content: [{ type: "text", text: JSON.stringify(success(getWorkspaceOverview(latest))) }] };
+    });
+    server.registerTool("list_files", {
+        description: "List indexed files (bounded, deterministically ordered).",
+        inputSchema: {
+            language: z.string().optional(),
+            kind: z.enum(["source", "test", "documentation", "config", "generated", "unknown"]).optional(),
+            limit: z.number().int().positive().max(1000).default(100),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listFilesPage(latest, {
+                        language: args.language,
+                        kind: args.kind,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("list_symbols", {
+        description: "List indexed symbols (bounded, deterministically ordered).",
+        inputSchema: {
+            language: z.string().optional(),
+            kind: z
+                .enum(["function", "class", "method", "interface", "type", "enum", "constant", "variable", "module", "namespace", "component", "route", "test", "unknown"])
+                .optional(),
+            packageId: z.string().optional(),
+            limit: z.number().int().positive().max(1000).default(100),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listSymbolsPage(latest, {
+                        language: args.language,
+                        kind: args.kind,
+                        packageId: args.packageId,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("list_packages", {
+        description: "List indexed packages (bounded, deterministically ordered).",
+        inputSchema: {
+            ecosystem: z.enum(["npm", "python", "unknown"]).optional(),
+            limit: z.number().int().positive().max(500).default(50),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listPackagesPage(latest, {
+                        ecosystem: args.ecosystem,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("list_public_apis", {
+        description: "List public APIs (bounded, deterministically ordered).",
+        inputSchema: {
+            stability: z.enum(["stable", "experimental", "deprecated", "internal", "test-only", "unknown"]).optional(),
+            packageId: z.string().optional(),
+            limit: z.number().int().positive().max(1000).default(100),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listPublicApisPage(latest, {
+                        stability: args.stability,
+                        packageId: args.packageId,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("list_relationships", {
+        description: "List relationships (bounded, deterministically ordered).",
+        inputSchema: {
+            type: z
+                .enum([
+                "defines",
+                "contains",
+                "documents",
+                "tests",
+                "covers",
+                "imports",
+                "exports",
+                "explicit_coverage",
+                "explicit_example",
+                "resolved_direct_import",
+                "resolved_direct_usage"
+            ])
+                .optional(),
+            limit: z.number().int().positive().max(1000).default(100),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listRelationshipsPage(latest, {
+                        type: args.type,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("list_diagnostics", {
+        description: "List diagnostics (bounded, deterministically ordered).",
+        inputSchema: {
+            severity: z.enum(["info", "warning", "error"]).optional(),
+            category: z.enum(["documentation", "indexing", "resolution", "style", "security", "determinism"]).optional(),
+            limit: z.number().int().positive().max(500).default(50),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listDiagnosticsPage(latest, {
+                        severity: args.severity,
+                        category: args.category,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("search_symbols", {
+        description: "Search symbols with deterministic ranking and per-result match reasons.",
+        inputSchema: {
+            query: z.string(),
+            kind: z
+                .enum(["function", "class", "method", "interface", "type", "enum", "constant", "variable", "module", "namespace", "component", "route", "test", "unknown"])
+                .optional(),
+            language: z.string().optional(),
+            packageId: z.string().optional(),
+            publicOnly: z.boolean().optional(),
+            capabilityId: z.string().optional(),
+            hasExamples: z.boolean().optional(),
+            hasTests: z.boolean().optional(),
+            limit: z.number().int().positive().max(200).default(20),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(searchSymbols(latest, {
+                        query: args.query,
+                        kind: args.kind,
+                        language: args.language,
+                        packageId: args.packageId,
+                        publicOnly: args.publicOnly,
+                        capabilityId: args.capabilityId,
+                        hasExamples: args.hasExamples,
+                        hasTests: args.hasTests,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_symbol_context", {
+        description: "Get symbol details and optional source preview.",
+        inputSchema: {
+            symbolId: z.string(),
+            includeSource: z.boolean().default(false),
+            includeEditingContext: z.boolean().default(false),
+            editingContextLimit: z.number().int().positive().max(25).optional(),
+            maxSourceLines: z.number().int().positive().max(200).default(80)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        const context = getSymbolContext(latest, args.symbolId, {
+            includeEditingContext: args.includeEditingContext,
+            editingContextLimit: args.editingContextLimit
+        });
+        if (!context)
+            return { content: [{ type: "text", text: JSON.stringify(failure("symbol_not_found", "Symbol not found.")) }] };
+        const { symbol, editingContext } = context;
+        let sourcePreview;
+        const bounded = getBoundedSourcePreview({
+            workspaceRoot: latestWorkspace,
+            relativePath: symbol.filePath,
+            includeSource: args.includeSource,
+            maxSourceLines: Math.min(args.maxSourceLines, latestLimits.maxSourcePreviewLines),
+            maxFileSizeBytes: latestLimits.maxFileSizeBytes
+        });
+        if (bounded.allowed) {
+            sourcePreview = bounded.source;
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success({
+                        symbol,
+                        editingContext,
+                        sourcePreview,
+                        sourceAccess: bounded.allowed ? "granted" : bounded.reason
+                    }))
+                }
+            ]
+        };
+    });
+    server.registerTool("list_capabilities", {
+        description: "List capabilities (bounded, deterministically ordered).",
+        inputSchema: {
+            stability: z.enum(["stable", "experimental", "deprecated", "internal", "test-only", "unknown"]).optional(),
+            limit: z.number().int().positive().max(500).default(50),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listCapabilitiesPage(latest, { stability: args.stability, limit: args.limit, offset: args.offset })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_capability_context", {
+        description: "Get capability context.",
+        inputSchema: {
+            capabilityId: z.string(),
+            maxPublicApis: z.number().int().positive().max(1000).optional(),
+            maxSymbols: z.number().int().positive().max(2000).optional(),
+            maxExamples: z.number().int().positive().max(1000).optional(),
+            maxTests: z.number().int().positive().max(1000).optional(),
+            maxDiagnostics: z.number().int().positive().max(5000).optional()
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        const capability = getCapabilityContext(latest, args.capabilityId, {
+            maxPublicApis: args.maxPublicApis,
+            maxSymbols: args.maxSymbols,
+            maxExamples: args.maxExamples,
+            maxTests: args.maxTests,
+            maxDiagnostics: args.maxDiagnostics
+        });
+        if (!capability)
+            return { content: [{ type: "text", text: JSON.stringify(failure("capability_not_found", "Capability not found.")) }] };
+        return { content: [{ type: "text", text: JSON.stringify(success(capability)) }] };
+    });
+    server.registerTool("search_public_apis", {
+        description: "Search public APIs with deterministic ranking and per-result match reasons.",
+        inputSchema: {
+            query: z.string(),
+            stability: z.enum(["stable", "experimental", "deprecated", "internal", "test-only", "unknown"]).optional(),
+            packageId: z.string().optional(),
+            language: z.string().optional(),
+            capabilityId: z.string().optional(),
+            hasExamples: z.boolean().optional(),
+            hasTests: z.boolean().optional(),
+            limit: z.number().int().positive().max(200).default(20),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(searchPublicApis(latest, {
+                        query: args.query,
+                        stability: args.stability,
+                        packageId: args.packageId,
+                        language: args.language,
+                        capabilityId: args.capabilityId,
+                        hasExamples: args.hasExamples,
+                        hasTests: args.hasTests,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_public_api_context", {
+        description: "Get public API context bundle.",
+        inputSchema: {
+            publicApiId: z.string(),
+            maxCapabilities: z.number().int().positive().max(1000).optional(),
+            maxExamples: z.number().int().positive().max(1000).optional(),
+            maxTests: z.number().int().positive().max(1000).optional(),
+            maxDiagnostics: z.number().int().positive().max(5000).optional(),
+            includeEditingContext: z.boolean().default(false),
+            editingContextLimit: z.number().int().positive().max(25).optional()
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        const context = getPublicApiContext(latest, args.publicApiId, {
+            maxCapabilities: args.maxCapabilities,
+            maxExamples: args.maxExamples,
+            maxTests: args.maxTests,
+            maxDiagnostics: args.maxDiagnostics,
+            includeEditingContext: args.includeEditingContext,
+            editingContextLimit: args.editingContextLimit
+        });
+        if (!context)
+            return { content: [{ type: "text", text: JSON.stringify(failure("public_api_not_found", "Public API not found.")) }] };
+        return { content: [{ type: "text", text: JSON.stringify(success(context)) }] };
+    });
+    server.registerTool("list_examples", {
+        description: "List example records (bounded, deterministically ordered) with optional capability/public API filtering.",
+        inputSchema: {
+            capabilityId: z.string().optional(),
+            publicApiId: z.string().optional(),
+            limit: z.number().int().positive().max(500).default(50),
+            offset: z.number().int().min(0).default(0)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listExamplesPage(latest, {
+                        capabilityId: args.capabilityId,
+                        publicApiId: args.publicApiId,
+                        limit: args.limit,
+                        offset: args.offset
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("find_reuse_candidates", {
+        description: "Find deterministic metadata-only reuse candidates.",
+        inputSchema: {
+            query: z.string(),
+            capabilityId: z.string().optional(),
+            packageId: z.string().optional(),
+            limit: z.number().int().positive().max(100).default(10)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(findReuseCandidates(latest, {
+                        query: args.query,
+                        capabilityId: args.capabilityId,
+                        packageId: args.packageId,
+                        limit: args.limit
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("validate_catalogue", {
+        description: "Validate indexed catalogue diagnostics.",
+        inputSchema: {
+            failOn: z.enum(["info", "warning", "error", "never"]).default("warning")
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        const failed = shouldFailFromDiagnostics(args.failOn, latest.diagnostics);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success({
+                        valid: !failed,
+                        diagnostics: latest.diagnostics
+                    }))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_dependency_neighborhood", {
+        description: "Get dependency neighborhood for a file path.",
+        inputSchema: {
+            path: z.string(),
+            depth: z.number().int().min(0).max(10).default(1),
+            direction: z.enum(["imports", "imported_by", "both"]).default("both")
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(getDependencyNeighborhood(latest, { path: args.path, depth: args.depth, direction: args.direction })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_adoption_audit", {
+        description: "Get deterministic documentation adoption audit.",
+        inputSchema: {
+            includeInfo: z.boolean().default(true),
+            includeGenerated: z.boolean().default(false),
+            maxGaps: z.number().int().min(1).max(5000).default(500)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(getAdoptionAudit(latest, {
+                        includeInfo: args.includeInfo,
+                        includeGenerated: args.includeGenerated,
+                        maxGaps: args.maxGaps
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_adoption_plan", {
+        description: "Get grouped adoption recommendations.",
+        inputSchema: {
+            includeInfo: z.boolean().default(true),
+            includeGenerated: z.boolean().default(false),
+            maxGaps: z.number().int().min(1).max(5000).default(500)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(getAdoptionPlan(latest, {
+                        includeInfo: args.includeInfo,
+                        includeGenerated: args.includeGenerated,
+                        maxGaps: args.maxGaps
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("list_documentation_templates", {
+        description: "List available static documentation templates.",
+        inputSchema: {}
+    }, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(success({ templates: listDocumentationTemplates() }))
+            }
+        ]
+    }));
+    server.registerTool("get_documentation_template", {
+        description: "Get a static documentation template by template ID.",
+        inputSchema: {
+            templateId: z.string()
+        }
+    }, async (args) => {
+        const available = listDocumentationTemplateIds();
+        if (!available.includes(args.templateId)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(failure("template_not_found", `Unknown template ${args.templateId}.`))
+                    }
+                ]
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(getDocumentationTemplate(args.templateId)))
+                }
+            ]
+        };
+    });
+    server.registerTool("recommend_config", {
+        description: "Recommend read-only exclude patterns for high-noise generated trees currently indexed (advisory; never writes config).",
+        inputSchema: {
+            limit: z.number().int().positive().max(200).default(50)
+        }
+    }, async (args) => {
+        if (!latest)
+            return catalogueNotLoadedContent();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(recommendConfig(latest, { limit: args.limit })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_dogfood_report", {
+        description: "Get a compact dogfood quality report for the latest indexed snapshot.",
+        inputSchema: {
+            maxDiagnostics: z.number().int().min(1).max(200).default(20),
+            maxGaps: z.number().int().min(1).max(200).default(20)
+        }
+    }, async (args) => {
+        if (!latest) {
+            return catalogueNotLoadedContent();
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(getDogfoodReport(latest, {
+                        maxDiagnostics: args.maxDiagnostics,
+                        maxGaps: args.maxGaps
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("compare_catalogues", {
+        description: "Compare two committed Schema 2 catalogues and optionally write a comparison artefact.",
+        inputSchema: {
+            baseWorkspaceRoot: z.string(),
+            baseCatalogueDir: z.string().default(".mapwright"),
+            headWorkspaceRoot: z.string(),
+            headCatalogueDir: z.string().default(".mapwright"),
+            outputWorkspaceRoot: z.string().optional(),
+            writeDir: z.string().optional()
+        }
+    }, async (args) => {
+        const prior = activeComparison;
+        const pair = loadCataloguePair({
+            baseWorkspaceRoot: args.baseWorkspaceRoot,
+            baseCatalogueDir: args.baseCatalogueDir ?? ".mapwright",
+            headWorkspaceRoot: args.headWorkspaceRoot,
+            headCatalogueDir: args.headCatalogueDir ?? ".mapwright"
+        });
+        if (!pair.ok) {
+            setActiveComparison(prior);
+            return { content: [{ type: "text", text: JSON.stringify(failure(pair.error.code, pair.error.message)) }] };
+        }
+        const compared = compareCatalogues(pair.base, pair.head, DEFAULT_COMPARISON_OPTIONS);
+        if (!compared.ok) {
+            setActiveComparison(prior);
+            return { content: [{ type: "text", text: JSON.stringify(failure(compared.error.code, compared.error.message)) }] };
+        }
+        if (args.writeDir) {
+            const outputWorkspace = args.outputWorkspaceRoot ?? args.baseWorkspaceRoot;
+            const containment = assertComparisonPathContained(outputWorkspace, args.writeDir);
+            if (containment) {
+                setActiveComparison(prior);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(failure(containment.code, containment.message)) }]
+                };
+            }
+            const resolvedWrite = path.isAbsolute(args.writeDir)
+                ? path.resolve(args.writeDir)
+                : path.resolve(outputWorkspace, args.writeDir);
+            const written = writeComparisonArtefact(resolvedWrite, compared.comparison);
+            if (!written.ok) {
+                setActiveComparison(prior);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(failure(written.error.code, written.error.message)) }]
+                };
+            }
+        }
+        setActiveComparison(compared.comparison);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success({
+                        comparisonId: compared.comparison.manifest.comparisonId,
+                        counts: compared.comparison.manifest.counts,
+                        aggregateCompatibility: compared.comparison.manifest.aggregateCompatibility,
+                        warnings: compared.comparison.warnings ?? []
+                    }))
+                }
+            ]
+        };
+    });
+    server.registerTool("load_comparison", {
+        description: "Load a written comparison artefact without reading source repositories.",
+        inputSchema: {
+            workspaceRoot: z.string(),
+            comparisonDir: z.string()
+        }
+    }, async (args) => {
+        const prior = activeComparison;
+        const containment = assertComparisonPathContained(args.workspaceRoot, args.comparisonDir);
+        if (containment) {
+            setActiveComparison(prior);
+            return {
+                content: [{ type: "text", text: JSON.stringify(failure(containment.code, containment.message)) }]
+            };
+        }
+        const resolved = path.isAbsolute(args.comparisonDir)
+            ? path.resolve(args.comparisonDir)
+            : path.resolve(args.workspaceRoot, args.comparisonDir);
+        const loaded = loadComparisonArtefact(resolved);
+        if (!loaded.ok) {
+            setActiveComparison(prior);
+            return {
+                content: [{ type: "text", text: JSON.stringify(failure(loaded.error.code, loaded.error.message)) }]
+            };
+        }
+        setActiveComparison(loaded.comparison);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success({
+                        comparisonId: loaded.comparison.manifest.comparisonId,
+                        counts: loaded.comparison.manifest.counts,
+                        aggregateCompatibility: loaded.comparison.manifest.aggregateCompatibility
+                    }))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_change_summary", {
+        description: "Summarize the active comparison counts and aggregate compatibility.",
+        inputSchema: {}
+    }, async () => {
+        if (!activeComparison) {
+            return { content: [{ type: "text", text: JSON.stringify(comparisonNotLoadedFailure()) }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(success(getChangeSummary(activeComparison))) }]
+        };
+    });
+    server.registerTool("list_changes", {
+        description: "List change records from the active comparison with deterministic ordering and pagination.",
+        inputSchema: {
+            domain: z.string().optional(),
+            status: z.string().optional(),
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().positive().max(200).default(50)
+        }
+    }, async (args) => {
+        if (!activeComparison) {
+            return { content: [{ type: "text", text: JSON.stringify(comparisonNotLoadedFailure()) }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(listChanges(activeComparison, {
+                        domain: args.domain,
+                        status: args.status,
+                        offset: args.offset,
+                        limit: args.limit
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_change", {
+        description: "Get a single change record from the active comparison.",
+        inputSchema: {
+            changeId: z.string()
+        }
+    }, async (args) => {
+        if (!activeComparison) {
+            return { content: [{ type: "text", text: JSON.stringify(comparisonNotLoadedFailure()) }] };
+        }
+        const change = getChange(activeComparison, args.changeId);
+        if (!change) {
+            return { content: [{ type: "text", text: JSON.stringify(failure("change_not_found", `Unknown changeId ${args.changeId}`)) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(success(change)) }] };
+    });
+    server.registerTool("get_compatibility_report", {
+        description: "Return compatibility findings and aggregate classification for the active comparison.",
+        inputSchema: {
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().positive().max(200).default(50)
+        }
+    }, async (args) => {
+        if (!activeComparison) {
+            return { content: [{ type: "text", text: JSON.stringify(comparisonNotLoadedFailure()) }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(success(getCompatibilityReport(activeComparison, {
+                        offset: args.offset,
+                        limit: args.limit
+                    })))
+                }
+            ]
+        };
+    });
+    server.registerTool("get_change_impact", {
+        description: "Compute bounded base/head impact for a change using the Model A graph index.",
+        inputSchema: {
+            changeId: z.string(),
+            maxDepth: z.number().int().min(1).max(8).default(3),
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().positive().max(200).default(50)
+        }
+    }, async (args) => {
+        if (!activeComparison) {
+            return { content: [{ type: "text", text: JSON.stringify(comparisonNotLoadedFailure()) }] };
+        }
+        const impact = getChangeImpact(activeComparison, args.changeId, {
+            maxDepth: args.maxDepth,
+            offset: args.offset,
+            limit: args.limit
+        });
+        if (!impact) {
+            return { content: [{ type: "text", text: JSON.stringify(failure("change_not_found", `Unknown changeId ${args.changeId}`)) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(success(impact)) }] };
+    });
+    server.registerTool("check_catalogue_drift", {
+        description: "Explicitly index the workspace in memory and compare against a committed catalogue without writing files.",
+        inputSchema: {
+            workspaceRoot: z.string(),
+            catalogueDir: z.string().default(".mapwright")
+        }
+    }, async (args) => {
+        const result = checkCatalogueDrift({
+            workspaceRoot: args.workspaceRoot,
+            catalogueDir: args.catalogueDir ?? ".mapwright"
+        });
+        if (!result.ok) {
+            return { content: [{ type: "text", text: JSON.stringify(failure(result.error.code, result.error.message)) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(success(result.data)) }] };
+    });
+}