mcp-adr-analysis-server 2.1.9 → 2.1.20

package/dist/src/utils/resource-versioning.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Resource Versioning and Metadata Tracking
+ *
+ * Provides version control for MCP resources, enabling:
+ * - Semantic versioning (MAJOR.MINOR.PATCH)
+ * - Backward compatibility checking
+ * - Version migration support
+ * - Metadata tracking (creation, updates, changelog)
+ */
+import { URLSearchParams } from 'url';
+/**
+ * Semantic version structure
+ */
+export interface SemanticVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/**
+ * Resource metadata for tracking changes
+ */
+export interface ResourceMetadata {
+    version: string;
+    createdAt: string;
+    updatedAt: string;
+    schemaVersion: string;
+    changelog?: ChangelogEntry[];
+    deprecationNotice?: DeprecationNotice;
+}
+/**
+ * Changelog entry for tracking changes
+ */
+export interface ChangelogEntry {
+    version: string;
+    date: string;
+    changes: string[];
+    breakingChanges?: string[];
+    author?: string;
+}
+/**
+ * Deprecation notice for resources
+ */
+export interface DeprecationNotice {
+    deprecatedIn: string;
+    removedIn?: string;
+    reason: string;
+    migration: string;
+}
+/**
+ * Version comparison result
+ */
+export declare enum VersionComparisonResult {
+    MAJOR_BREAKING = "major_breaking",
+    MINOR_COMPATIBLE = "minor_compatible",
+    PATCH_COMPATIBLE = "patch_compatible",
+    EQUAL = "equal",
+    OLDER = "older"
+}
+/**
+ * Parse semantic version string to object
+ */
+export declare function parseVersion(versionString: string): SemanticVersion;
+/**
+ * Convert semantic version object to string
+ */
+export declare function versionToString(version: SemanticVersion): string;
+/**
+ * Compare two semantic versions
+ * @returns VersionComparisonResult indicating relationship
+ */
+export declare function compareVersions(current: string, requested: string): VersionComparisonResult;
+/**
+ * Check if two versions are compatible (same major version)
+ */
+export declare function isCompatible(version1: string, version2: string): boolean;
+/**
+ * Increment version based on change type
+ */
+export declare function incrementVersion(current: string, changeType: 'major' | 'minor' | 'patch'): string;
+/**
+ * Create initial resource metadata
+ */
+export declare function createResourceMetadata(version?: string): ResourceMetadata;
+/**
+ * Update resource metadata with new version
+ */
+export declare function updateResourceMetadata(current: ResourceMetadata, newVersion: string, changes: string[], breakingChanges?: string[]): ResourceMetadata;
+/**
+ * Mark resource as deprecated
+ */
+export declare function deprecateResource(metadata: ResourceMetadata, reason: string, migration: string, removedIn?: string): ResourceMetadata;
+/**
+ * Check if resource is deprecated
+ */
+export declare function isDeprecated(metadata: ResourceMetadata): boolean;
+/**
+ * Extract version from URI search parameters
+ */
+export declare function extractVersionFromParams(searchParams?: URLSearchParams): string | null;
+/**
+ * Validate requested version against available versions
+ */
+export declare function validateVersionRequest(requested: string | null, current: string, supportedVersions: string[]): {
+    valid: boolean;
+    version: string;
+    warning?: string;
+};
+/**
+ * Generate version compatibility matrix
+ */
+export declare function generateCompatibilityMatrix(versions: string[]): Map<string, string[]>;
+/**
+ * Get changelog for specific version range
+ */
+export declare function getChangelogForRange(metadata: ResourceMetadata, fromVersion: string, toVersion: string): ChangelogEntry[];
+/**
+ * Extract breaking changes from changelog
+ */
+export declare function getBreakingChanges(metadata: ResourceMetadata): ChangelogEntry[];
+/**
+ * Format metadata for display
+ */
+export declare function formatMetadata(metadata: ResourceMetadata): string;
+//# sourceMappingURL=resource-versioning.d.ts.map

package/dist/src/utils/resource-versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-versioning.d.ts","sourceRoot":"","sources":["../../../src/utils/resource-versioning.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/resource-versioning.js

@@ -0,0 +1,272 @@
+/**
+ * Resource Versioning and Metadata Tracking
+ *
+ * Provides version control for MCP resources, enabling:
+ * - Semantic versioning (MAJOR.MINOR.PATCH)
+ * - Backward compatibility checking
+ * - Version migration support
+ * - Metadata tracking (creation, updates, changelog)
+ */
+/**
+ * Version comparison result
+ */
+export var VersionComparisonResult;
+(function (VersionComparisonResult) {
+    VersionComparisonResult["MAJOR_BREAKING"] = "major_breaking";
+    VersionComparisonResult["MINOR_COMPATIBLE"] = "minor_compatible";
+    VersionComparisonResult["PATCH_COMPATIBLE"] = "patch_compatible";
+    VersionComparisonResult["EQUAL"] = "equal";
+    VersionComparisonResult["OLDER"] = "older";
+})(VersionComparisonResult || (VersionComparisonResult = {}));
+/**
+ * Parse semantic version string to object
+ */
+export function parseVersion(versionString) {
+    const match = versionString.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid semantic version: ${versionString}`);
+    }
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+    };
+}
+/**
+ * Convert semantic version object to string
+ */
+export function versionToString(version) {
+    return `${version.major}.${version.minor}.${version.patch}`;
+}
+/**
+ * Compare two semantic versions
+ * @returns VersionComparisonResult indicating relationship
+ */
+export function compareVersions(current, requested) {
+    const currentV = parseVersion(current);
+    const requestedV = parseVersion(requested);
+    // Equal versions
+    if (currentV.major === requestedV.major &&
+        currentV.minor === requestedV.minor &&
+        currentV.patch === requestedV.patch) {
+        return VersionComparisonResult.EQUAL;
+    }
+    // Current is older than requested
+    if (currentV.major < requestedV.major ||
+        (currentV.major === requestedV.major && currentV.minor < requestedV.minor) ||
+        (currentV.major === requestedV.major &&
+            currentV.minor === requestedV.minor &&
+            currentV.patch < requestedV.patch)) {
+        return VersionComparisonResult.OLDER;
+    }
+    // Current is newer - check compatibility
+    if (currentV.major > requestedV.major) {
+        return VersionComparisonResult.MAJOR_BREAKING;
+    }
+    if (currentV.minor > requestedV.minor) {
+        return VersionComparisonResult.MINOR_COMPATIBLE;
+    }
+    return VersionComparisonResult.PATCH_COMPATIBLE;
+}
+/**
+ * Check if two versions are compatible (same major version)
+ */
+export function isCompatible(version1, version2) {
+    const v1 = parseVersion(version1);
+    const v2 = parseVersion(version2);
+    return v1.major === v2.major;
+}
+/**
+ * Increment version based on change type
+ */
+export function incrementVersion(current, changeType) {
+    const version = parseVersion(current);
+    switch (changeType) {
+        case 'major':
+            return versionToString({ major: version.major + 1, minor: 0, patch: 0 });
+        case 'minor':
+            return versionToString({ major: version.major, minor: version.minor + 1, patch: 0 });
+        case 'patch':
+            return versionToString({ major: version.major, minor: version.minor, patch: version.patch + 1 });
+        default:
+            throw new Error(`Invalid change type: ${changeType}`);
+    }
+}
+/**
+ * Create initial resource metadata
+ */
+export function createResourceMetadata(version = '1.0.0') {
+    const now = new Date().toISOString();
+    return {
+        version,
+        createdAt: now,
+        updatedAt: now,
+        schemaVersion: version,
+    };
+}
+/**
+ * Update resource metadata with new version
+ */
+export function updateResourceMetadata(current, newVersion, changes, breakingChanges) {
+    const now = new Date().toISOString();
+    const changelogEntry = {
+        version: newVersion,
+        date: now,
+        changes,
+    };
+    // Only add breakingChanges if provided
+    if (breakingChanges) {
+        changelogEntry.breakingChanges = breakingChanges;
+    }
+    return {
+        ...current,
+        version: newVersion,
+        updatedAt: now,
+        changelog: [...(current.changelog || []), changelogEntry],
+    };
+}
+/**
+ * Mark resource as deprecated
+ */
+export function deprecateResource(metadata, reason, migration, removedIn) {
+    const deprecationNotice = {
+        deprecatedIn: metadata.version,
+        reason,
+        migration,
+    };
+    // Only add removedIn if provided
+    if (removedIn) {
+        deprecationNotice.removedIn = removedIn;
+    }
+    return {
+        ...metadata,
+        deprecationNotice,
+    };
+}
+/**
+ * Check if resource is deprecated
+ */
+export function isDeprecated(metadata) {
+    return metadata.deprecationNotice !== undefined;
+}
+/**
+ * Extract version from URI search parameters
+ */
+export function extractVersionFromParams(searchParams) {
+    if (!searchParams) {
+        return null;
+    }
+    return searchParams.get('version');
+}
+/**
+ * Validate requested version against available versions
+ */
+export function validateVersionRequest(requested, current, supportedVersions) {
+    // No version requested - use current
+    if (!requested) {
+        return { valid: true, version: current };
+    }
+    // Check if requested version is supported
+    if (!supportedVersions.includes(requested)) {
+        return {
+            valid: false,
+            version: current,
+            warning: `Version ${requested} not supported. Using current version ${current}. Supported: ${supportedVersions.join(', ')}`,
+        };
+    }
+    // Check compatibility
+    const comparison = compareVersions(current, requested);
+    if (comparison === VersionComparisonResult.MAJOR_BREAKING) {
+        return {
+            valid: true,
+            version: requested,
+            warning: `Warning: Version ${requested} has breaking changes from current ${current}`,
+        };
+    }
+    return { valid: true, version: requested };
+}
+/**
+ * Generate version compatibility matrix
+ */
+export function generateCompatibilityMatrix(versions) {
+    const matrix = new Map();
+    for (const version of versions) {
+        const compatible = versions.filter((v) => isCompatible(version, v));
+        matrix.set(version, compatible);
+    }
+    return matrix;
+}
+/**
+ * Get changelog for specific version range
+ */
+export function getChangelogForRange(metadata, fromVersion, toVersion) {
+    if (!metadata.changelog) {
+        return [];
+    }
+    const from = parseVersion(fromVersion);
+    const to = parseVersion(toVersion);
+    return metadata.changelog.filter((entry) => {
+        const entryVersion = parseVersion(entry.version);
+        // Version is within range (exclusive of fromVersion, inclusive of toVersion)
+        const isAfterFrom = entryVersion.major > from.major ||
+            (entryVersion.major === from.major && entryVersion.minor > from.minor) ||
+            (entryVersion.major === from.major &&
+                entryVersion.minor === from.minor &&
+                entryVersion.patch > from.patch);
+        const isBeforeOrEqualTo = entryVersion.major < to.major ||
+            (entryVersion.major === to.major && entryVersion.minor < to.minor) ||
+            (entryVersion.major === to.major &&
+                entryVersion.minor === to.minor &&
+                entryVersion.patch <= to.patch);
+        return isAfterFrom && isBeforeOrEqualTo;
+    });
+}
+/**
+ * Extract breaking changes from changelog
+ */
+export function getBreakingChanges(metadata) {
+    if (!metadata.changelog) {
+        return [];
+    }
+    return metadata.changelog.filter((entry) => entry.breakingChanges && entry.breakingChanges.length > 0);
+}
+/**
+ * Format metadata for display
+ */
+export function formatMetadata(metadata) {
+    const lines = [
+        `Version: ${metadata.version}`,
+        `Schema: ${metadata.schemaVersion}`,
+        `Created: ${metadata.createdAt}`,
+        `Updated: ${metadata.updatedAt}`,
+    ];
+    if (metadata.deprecationNotice) {
+        lines.push('');
+        lines.push('⚠️  DEPRECATED');
+        lines.push(`Deprecated in: ${metadata.deprecationNotice.deprecatedIn}`);
+        if (metadata.deprecationNotice.removedIn) {
+            lines.push(`Will be removed in: ${metadata.deprecationNotice.removedIn}`);
+        }
+        lines.push(`Reason: ${metadata.deprecationNotice.reason}`);
+        lines.push(`Migration: ${metadata.deprecationNotice.migration}`);
+    }
+    if (metadata.changelog && metadata.changelog.length > 0) {
+        lines.push('');
+        lines.push('Recent Changes:');
+        const recentChanges = metadata.changelog.slice(-3).reverse();
+        for (const entry of recentChanges) {
+            lines.push(`  v${entry.version} (${entry.date})`);
+            for (const change of entry.changes) {
+                lines.push(`    - ${change}`);
+            }
+            if (entry.breakingChanges && entry.breakingChanges.length > 0) {
+                lines.push('    ⚠️  Breaking Changes:');
+                for (const breaking of entry.breakingChanges) {
+                    lines.push(`      - ${breaking}`);
+                }
+            }
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=resource-versioning.js.map

package/dist/src/utils/resource-versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-versioning.js","sourceRoot":"","sources":["../../../src/utils/resource-versioning.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/root-manager.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Root Manager for MCP File Access Control
+ *
+ * Implements MCP best practices for file system access control using "roots".
+ * Roots are predefined directories that the server is allowed to access,
+ * providing both security and autonomous file discovery for Claude.
+ *
+ * @see https://modelcontextprotocol.io/docs/concepts/roots
+ */
+/**
+ * A root is a directory that the MCP server is allowed to access
+ */
+export interface Root {
+    /** Unique identifier for the root */
+    name: string;
+    /** Absolute path to the root directory */
+    path: string;
+    /** Human-readable description of what this root contains */
+    description: string;
+}
+/**
+ * Manages file system roots for MCP server access control
+ *
+ * @example
+ * ```typescript
+ * const rootManager = new RootManager('/path/to/project', '/path/to/project/docs/adrs');
+ *
+ * // Check if path is allowed
+ * if (rootManager.isPathAllowed('/path/to/project/src/index.ts')) {
+ *   // Access granted
+ * }
+ *
+ * // List all roots for Claude
+ * const roots = rootManager.listRoots();
+ * ```
+ */
+export declare class RootManager {
+    private roots;
+    /**
+     * Initialize root manager with project and ADR paths
+     *
+     * @param projectPath - Path to the project root directory
+     * @param adrDirectory - Path to the ADR directory
+     */
+    constructor(projectPath: string, adrDirectory: string);
+    /**
+     * Check if a path is within accessible roots
+     *
+     * @param targetPath - Path to check (can be relative or absolute)
+     * @returns true if path is within any root, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (!rootManager.isPathAllowed(userPath)) {
+     *   throw new Error('Access denied: Path is outside accessible roots');
+     * }
+     * ```
+     */
+    isPathAllowed(targetPath: string): boolean;
+    /**
+     * List all accessible roots
+     *
+     * @returns Array of root definitions
+     *
+     * @example
+     * ```typescript
+     * const roots = rootManager.listRoots();
+     * roots.forEach(root => {
+     *   console.log(`${root.name}: ${root.path}`);
+     * });
+     * ```
+     */
+    listRoots(): Root[];
+    /**
+     * Get which root a path belongs to
+     *
+     * @param targetPath - Path to check
+     * @returns Root that contains this path, or null if outside all roots
+     *
+     * @example
+     * ```typescript
+     * const root = rootManager.getRootForPath('/path/to/project/src/index.ts');
+     * if (root) {
+     *   console.log(`File is in ${root.name} root`);
+     * }
+     * ```
+     */
+    getRootForPath(targetPath: string): Root | null;
+    /**
+     * Get the relative path from root
+     *
+     * @param targetPath - Path to get relative path for
+     * @returns Relative path from root, or null if outside all roots
+     *
+     * @example
+     * ```typescript
+     * const relPath = rootManager.getRelativePathFromRoot('/path/to/project/src/index.ts');
+     * // Returns: 'src/index.ts'
+     * ```
+     */
+    getRelativePathFromRoot(targetPath: string): string | null;
+    /**
+     * Add a custom root (useful for testing or dynamic root management)
+     *
+     * @param name - Unique identifier for the root
+     * @param path - Absolute path to the root directory
+     * @param description - Human-readable description
+     */
+    addRoot(name: string, path: string, description: string): void;
+    /**
+     * Remove a root by name
+     *
+     * @param name - Name of the root to remove
+     * @returns true if root was removed, false if not found
+     */
+    removeRoot(name: string): boolean;
+}
+//# sourceMappingURL=root-manager.d.ts.map

package/dist/src/utils/root-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-manager.d.ts","sourceRoot":"","sources":["../../../src/utils/root-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAgC;IAE7C;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAiBrD;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAU1C;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,IAAI,EAAE;IAInB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAU/C;;;;;;;;;;;OAWG;IACH,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQ1D;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAQ9D;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGlC"}

package/dist/src/utils/root-manager.js

@@ -0,0 +1,154 @@
+/**
+ * Root Manager for MCP File Access Control
+ *
+ * Implements MCP best practices for file system access control using "roots".
+ * Roots are predefined directories that the server is allowed to access,
+ * providing both security and autonomous file discovery for Claude.
+ *
+ * @see https://modelcontextprotocol.io/docs/concepts/roots
+ */
+import { resolve, relative } from 'path';
+/**
+ * Manages file system roots for MCP server access control
+ *
+ * @example
+ * ```typescript
+ * const rootManager = new RootManager('/path/to/project', '/path/to/project/docs/adrs');
+ *
+ * // Check if path is allowed
+ * if (rootManager.isPathAllowed('/path/to/project/src/index.ts')) {
+ *   // Access granted
+ * }
+ *
+ * // List all roots for Claude
+ * const roots = rootManager.listRoots();
+ * ```
+ */
+export class RootManager {
+    roots = new Map();
+    /**
+     * Initialize root manager with project and ADR paths
+     *
+     * @param projectPath - Path to the project root directory
+     * @param adrDirectory - Path to the ADR directory
+     */
+    constructor(projectPath, adrDirectory) {
+        // Root 1: Project directory (entire codebase)
+        this.roots.set('project', {
+            name: 'project',
+            path: resolve(projectPath),
+            description: 'Project source code, configuration, and documentation',
+        });
+        // Root 2: ADR directory (may be inside project, but worth explicit access)
+        const resolvedAdrPath = resolve(adrDirectory);
+        this.roots.set('adrs', {
+            name: 'adrs',
+            path: resolvedAdrPath,
+            description: 'Architectural Decision Records',
+        });
+    }
+    /**
+     * Check if a path is within accessible roots
+     *
+     * @param targetPath - Path to check (can be relative or absolute)
+     * @returns true if path is within any root, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (!rootManager.isPathAllowed(userPath)) {
+     *   throw new Error('Access denied: Path is outside accessible roots');
+     * }
+     * ```
+     */
+    isPathAllowed(targetPath) {
+        const resolved = resolve(targetPath);
+        for (const root of this.roots.values()) {
+            if (resolved.startsWith(root.path)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * List all accessible roots
+     *
+     * @returns Array of root definitions
+     *
+     * @example
+     * ```typescript
+     * const roots = rootManager.listRoots();
+     * roots.forEach(root => {
+     *   console.log(`${root.name}: ${root.path}`);
+     * });
+     * ```
+     */
+    listRoots() {
+        return Array.from(this.roots.values());
+    }
+    /**
+     * Get which root a path belongs to
+     *
+     * @param targetPath - Path to check
+     * @returns Root that contains this path, or null if outside all roots
+     *
+     * @example
+     * ```typescript
+     * const root = rootManager.getRootForPath('/path/to/project/src/index.ts');
+     * if (root) {
+     *   console.log(`File is in ${root.name} root`);
+     * }
+     * ```
+     */
+    getRootForPath(targetPath) {
+        const resolved = resolve(targetPath);
+        for (const root of this.roots.values()) {
+            if (resolved.startsWith(root.path)) {
+                return root;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the relative path from root
+     *
+     * @param targetPath - Path to get relative path for
+     * @returns Relative path from root, or null if outside all roots
+     *
+     * @example
+     * ```typescript
+     * const relPath = rootManager.getRelativePathFromRoot('/path/to/project/src/index.ts');
+     * // Returns: 'src/index.ts'
+     * ```
+     */
+    getRelativePathFromRoot(targetPath) {
+        const root = this.getRootForPath(targetPath);
+        if (!root) {
+            return null;
+        }
+        return relative(root.path, resolve(targetPath));
+    }
+    /**
+     * Add a custom root (useful for testing or dynamic root management)
+     *
+     * @param name - Unique identifier for the root
+     * @param path - Absolute path to the root directory
+     * @param description - Human-readable description
+     */
+    addRoot(name, path, description) {
+        this.roots.set(name, {
+            name,
+            path: resolve(path),
+            description,
+        });
+    }
+    /**
+     * Remove a root by name
+     *
+     * @param name - Name of the root to remove
+     * @returns true if root was removed, false if not found
+     */
+    removeRoot(name) {
+        return this.roots.delete(name);
+    }
+}
+//# sourceMappingURL=root-manager.js.map